Create or update contacts in a batch

POST

/workspaces/{workspace}/contacts/batch

curl --request POST \
  --url https://api.sendtruss.com/v1/workspaces/example/contacts/batch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "contacts": [ { "reference": "example", "email": "example", "attributes": { "additionalProperty": "example" }, "tags": [ "example" ], "locale": "example", "marketing": { "state": "subscribed", "at": "example" }, "pixel_consent_at": "example" } ] }'

• Production

Up to 500 contacts, each by your reference and with the same fields as a single upsert. Each one is written or refused on its own, so the answer is 200 with one result per contact, in the order you sent them; a refused one carries its own code, message and doc_url.

Authorizations

• http

Parameters

Path Parameters

workspace

required

string

/^(?:[0-9A-Za-z]{26}|ref:[A-Za-z0-9._-]{1,128})$/

The workspace: our id, or ref: plus your reference for it, such as ref:cust_4821. A reference is letters, digits, ., _ and -, up to 128 characters, and needs no URL encoding.

Request Body^required

Media typeapplication/json

object

contacts

required

The contacts, each with its reference and the fields of a single upsert.

Array<object>

object

reference

required

string

email

string

attributes

object

key

additional properties

string | number | boolean | null

tags

Array<string>

locale

string | null

marketing

object

state

required

string

Allowed values: subscribed unsubscribed

at

required

string

pixel_consent_at

string | null

Responses

200

One result per contact, in the order you sent them: created or updated with its id, or refused with the code, message and doc_url a single upsert would answer with.

Media typeapplication/json

object

data

required

Array<object>

object

reference

required

string | null

result

required

string

Allowed values: created updated refused

id

string

code

string

message

string

errors

object

key

additional properties

Array<string>

contact

string

doc_url

string

Example

{
  "data": [
    {
      "result": "created"
    }
  ]
}

Headers

Request-Id

required

string format: uuid

This request’s id. Quote it when you ask us about the request.

401

The API key is missing, malformed, revoked or expired.

Media typeapplication/json

object

message

required

What went wrong, for a person to read. It may change, so branch on code.

string

code

required

What went wrong, for your code to branch on. A new code is not a breaking change.

string

Allowed values: unauthenticated

doc_url

required

The entry on our errors page that explains this code.

string format: uri

request_id

required

This request’s id, the same as its Request-Id header. Quote it when you ask us about the request.

string format: uuid

Example

{
  "code": "unauthenticated"
}

Headers

Request-Id

required

string format: uuid

This request’s id. Quote it when you ask us about the request.

404

Nothing is at this path for your key. Another platform’s or another workspace’s resource answers the same as one that doesn’t exist.

Media typeapplication/json

object

message

required

What went wrong, for a person to read. It may change, so branch on code.

string

code

required

What went wrong, for your code to branch on. A new code is not a breaking change.

string

Allowed values: not_found

doc_url

required

The entry on our errors page that explains this code.

string format: uri

request_id

required

This request’s id, the same as its Request-Id header. Quote it when you ask us about the request.

string format: uuid

Example

{
  "code": "not_found"
}

Headers

Request-Id

required

string format: uuid

This request’s id. Quote it when you ask us about the request.

422

The request is invalid. The code says why, and errors names each field at fault.

Media typeapplication/json

object

message

required

What went wrong, for a person to read. It may change, so branch on code.

string

code

required

What went wrong, for your code to branch on. A new code is not a breaking change.

string

Allowed values: validation_failed

errors

required

Each field that failed validation, by its path in the request, with its messages.

object

key

additional properties

Array<string>

doc_url

required

The entry on our errors page that explains this code.

string format: uri

request_id

required

This request’s id, the same as its Request-Id header. Quote it when you ask us about the request.

string format: uuid

Example

{
  "code": "validation_failed"
}

Headers

Request-Id

required

string format: uuid

This request’s id. Quote it when you ask us about the request.

429

Too many requests. Wait for the seconds in Retry-After.

Media typeapplication/json

object

message

required

What went wrong, for a person to read. It may change, so branch on code.

string

code

required

What went wrong, for your code to branch on. A new code is not a breaking change.

string

Allowed values: rate_limited

doc_url

required

The entry on our errors page that explains this code.

string format: uri

request_id

required

This request’s id, the same as its Request-Id header. Quote it when you ask us about the request.

string format: uuid

Example

{
  "code": "rate_limited"
}

Headers

Request-Id

required

string format: uuid

This request’s id. Quote it when you ask us about the request.

Retry-After

integer

Seconds to wait before trying again.