Vector
Appointments (SFTP)
Integration Guide

Appointment Ingestion API

Submit a single appointment to Vector over HTTPS instead of uploading a CSV file to SFTP. The JSON you send is converted into a one-row CSV and run through the same ingestion pipeline, so every rule in the Appointments guide applies: the Field Reference, required properties, and updates and cancels by Primary Identifier.

Endpoints

Queued

POST /1.0/entities/actions/integration/appointments/ingestJson?target=<uuid>

Returns as soon as the appointment is accepted, like dropping a file into the SFTP files/ folder. A 200 means “received”, not “imported”.

Synchronous

POST /1.0/entities/actions/integration/appointments/ingestJsonSync?target=<uuid>

Imports the appointment during the request and returns the import results. Use it when your system has to know a row failed before it moves on.

Base URL:https://api.withvector.com
Authentication:OAuth2 bearer token in the Authorization header. A missing or invalid token returns 401 or 403.
Content-Type:application/json

Query Parameters

ParameterStatusDescriptionExample
target
Required
UUID of your firm's appointment ingestion config, provided by your Vector Deployment Strategist. It must belong to the same firm as your API token and have API ingestion enabled.3f6c2a9e-8b1d-4e7a-9c55-2d0f1b7e4a10

Request Format

RuleDetails
Content typeapplication/json
BodyExactly one JSON object, which is one appointment. Arrays, bare strings, numbers and empty bodies are rejected.
KeysUse the Field Name values from the Field Reference as JSON keys, spelled exactly like the CSV column headers (for example "Primary Identifier").
ValuesEach field takes a single string value, formatted as in the Field Reference (ISO 8601 datetimes, "true" for flags).
Multiple valuesFor Purchase Order Numbers, Order Numbers and Trailer Numbers, send one comma-separated string, for example "PO12345, PO54321". Spaces around each value are trimmed and empty entries, such as a trailing comma, are ignored. Don't send a JSON array. An array like ["PO12345","PO54321"] may be stored as literal text instead of being read as a list, which produces broken values.
Empty fieldsLeaving a key out, sending null and sending "" all do the same thing: the field is left unchanged. Blank values are ignored, so you can't clear an existing value by sending an empty string. Sending "" on an update to an existing Primary Identifier does nothing for that field.
One per requestTo send a batch, make one request per appointment or use the SFTP path.

How the JSON becomes a row

Vector flattens the object into a single CSV row: keys become column headers and values become cells. Keep the object flat. A nested object becomes dotted column names ({"Origin": {"City": "..."}} becomes Origin.City), which won't match any field in the Field Reference.

Sample Request

The same appointment as the Sample CSV Row, written as JSON. Fields left empty in the CSV row are omitted here.

appointment.json
{
  "Primary Identifier": "APPT-20250601-001",
  "Purchase Order Numbers": "PO12345, PO54321",
  "Order Numbers": "12345, 54321",
  "Load Number": "LD-11633561",
  "Appointment Start Date/Time": "2025-06-01T14:00:00Z",
  "Appointment End Date/Time": "2025-06-01T16:00:00Z",
  "Appointment Facility": "FAC-DFW-01",
  "Appointment Type": "Inbound",
  "Load Type": "Live",
  "Origin Name": "Fort Worth DC",
  "Origin Location Source Identifier": "ORI-001",
  "Origin Location City": "Fort Worth",
  "Origin Location State / Province": "TX",
  "Destination Name": "Chicago Warehouse",
  "Destination Location Source Identifier": "DST-042",
  "Destination Location City": "Chicago",
  "Destination Location State / Province": "IL",
  "Carrier Name": "US XPRESS INC",
  "Carrier SCAC": "USXP",
  "Carrier DOT Number": "303024",
  "Reefer or Dry Load": "Dry",
  "Trailer Numbers": "TRL-123, TRL-456",
  "Customer": "Retail Corp"
}
cURL
curl -X POST \
  "https://api.withvector.com/1.0/entities/actions/integration/appointments/ingestJson?target=$TARGET" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @appointment.json

To update or cancel an appointment, send the same Primary Identifier again with the changed values, or with "Canceled": "true", exactly as on the SFTP path.

Responses

ingestJson · 200 OK
{
  "message": "Appointment queued for ingestion.",
  "data": {
    "filename": "<tracking filename>"
  }
}

data.filename is a tracking reference for this submission. Log it and give it to Vector Support when asking about a particular appointment. Treat it as opaque; don't parse it or rely on its format.

ingestJsonSync · 200 OK
{
  "message": "Appointment processed successfully.",
  "entityMappings": [
    {
      "row": 1,
      "alias": "<entity alias>",
      "uuid": "<Vector record ID>"
    }
  ],
  "importResults": {
    "csvImportStats": {
      "importAttempts": 1,
      "importErrors": 0,
      "importsCreated": 1
    },
    "errors": [],
    "status": "SUCCESS"
  }
}
Sync fieldTypeWhat it tells you
entityMappingsarrayOne entry per Vector record created from your appointment.
entityMappings[].rowintegerThe row the record came from. A JSON request is always one row.
entityMappings[].aliasstringThe kind of record created, as named in your ingestion config.
entityMappings[].uuidstringThe Vector ID of the created record. Store it to link your appointment to the Vector record.
importResults.csvImportStats.importAttemptsintegerRows attempted. Always 1 for a JSON request.
importResults.csvImportStats.importErrorsintegerRows that failed.
importResults.csvImportStats.importsCreatedintegerRows imported.
importResults.errorsarrayError details for any failed rows. Empty on success.
importResults.statusstringSUCCESS or FAILED. With one row per request, FAILED means your appointment was not imported.

Check importResults, not just the status code

ingestJsonSync returns 200 with “Appointment processed successfully.” whenever the import runs, even when the row failed validation. The appointment was imported only if importResults.status is SUCCESS and importErrors is 0.

Errors

Every error response is JSON in the form {"message": "<text>"}. Checks run in the order below. The target and permission checks happen before the body is read, so a request with problems in both returns the target or permission error first.

StatusmessageCauseFix
401 / 403—The bearer token is missing, expired or invalid.Get a new token and retry.
400target is requiredNo target query parameter.Add ?target=<uuid>.
400Invalid ingestion target.target isn't a valid UUID, or no ingestion config exists with that ID.Check that the UUID matches the config you were given.
403Access denied.The ingestion config belongs to a different firm than your API token.Use the config provisioned for your account, with a token issued to the same firm.
403API ingestion is not enabled for this pipeline.The config exists and is yours, but API ingestion is turned off for it.Ask your Vector Deployment Strategist to turn on API ingestion.
400Request body is required.The body is empty or only whitespace.Send one JSON object.
400Could not parse JSON payload.The body isn't valid JSON.Validate the JSON before sending.
400Unexpected JSON data, expected single JSON object.The body is valid JSON but not an object, for example an array of appointments.Send one object per request.
500An internal error occurred during ingestion processing.An unexpected failure on the server.Retry with backoff. If it persists, contact Vector Support with the request details.
500VariesThe ingestion config is incomplete on Vector's side (for example, ingestJson has no upload destination).Contact your Vector Deployment Strategist.

ingestJsonSync only

StatusmessageCauseFix
400SftpIngestConfigEntity is missing MultiEntityPayloadConfigThe config isn't set up for synchronous imports.Contact your Vector Deployment Strategist.
400Could not find payload config entity <uuid>The config points to field-mapping settings that don't exist.Contact your Vector Deployment Strategist.

Ready to integrate?

Contact the Vector integration team to get your API credentials, ingestion target, and personalized onboarding support.

Contact Integration Team