Upsert contacts in a batch

PUT/v1/contacts

Body parameters

application/json · array of records · required

name string required

Display name of the resource.

Minimum length: 1 character. · Maximum length: 255 characters.

ExampleNQD record

clientId string nullable

Optional client relationship for this contact. A contact may also reference a vendor; when both are provided they must resolve to the same party. A null clientId alone does not mean workspace ownership when vendorId is set.

Minimum length: 1 character. · Maximum length: 128 characters.

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1C

vendorId string nullable

Optional vendor relationship for this contact. A contact may also reference a client; when both are provided they must resolve to the same party. Both relationship IDs null means the current workspace owns the contact.

Minimum length: 1 character. · Maximum length: 128 characters.

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1C

description string nullable

Human-readable description of the resource.

Maximum length: 10000 characters.

ExampleConsulting services for January 2026

email string[] nullable

Email address associated with the identity.

at most 100 items

Example1 item

phone string[] nullable

phone for this contact.

at most 100 items

Example1 item

website string[] nullable

website for this contact.

at most 100 items

Example1 item

position string[] nullable

position for this contact.

at most 100 items

Example1 item

bankName string nullable

bank name for this contact.

Maximum length: 10000 characters.

ExampleNQD Bank

iban string nullable

iban for this contact.

Maximum length: 10000 characters.

ExampleSA0380000000608010167519

tags string[] nullable

Tags assigned to the record.

at most 100 items

Example1 item

id string required

Opaque identifier for this resource or reference.

Minimum length: 1 character. · Maximum length: 128 characters.

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1E

Headers

authorization string required

Bearer workspace API key.

ExampleBearer $NQD_API_KEY

workspace-id string required

Workspace scope for the request. Required for workspace operations and must belong to the authenticated identity.

Minimum length: 1 character. · Maximum length: 128 characters.

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1A

Send the complete writable representation or change set. Use the latest updatedAt for If-Match.

Response

200Success

Response headers

x-request-id string

Correlation identifier returned with every response for support and request tracing.

Example550e8400-e29b-41d4-a716-446655440000

data object[]

Returned records. Collections and batches use an array; single records use an object.

ShowHide 15 properties

data[].id string

Opaque identifier for this resource or reference.

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1E

data[].clientId string

Examplenull

data[].vendorId string

Examplenull

data[].name string

Display name of the record.

ExampleNQD record

data[].description string

Optional human-readable description of the record.

ExampleConsulting services for January 2026

data[].email string[]

Email address associated with the identity.

Example1 item

data[].phone string[]

phone for this contact.

Example1 item

data[].website string[]

website for this contact.

Example1 item

data[].position string[]

position for this contact.

Example1 item

data[].bankName string

bank name for this contact.

ExampleNQD Bank

data[].iban string

iban for this contact.

ExampleSA0380000000608010167519

data[].notes string

Notes attached to the record.

ExampleConsulting services

data[].tags string[] nullable

Tags assigned to the record.

Example1 item

data[].createdAt string

ISO 8601 timestamp for the authored or payment event. Recurring records preserve their scheduled occurrence.

Example2026-01-15T12:00:00.000Z

data[].updatedAt string

Timestamp used for stale-edit protection. Preserve the server value when updating.

Example2026-01-15T12:00:00.000Z

Possible errors

400 Invalid request

Response headers

x-request-id string

Correlation identifier returned with every response for support and request tracing.

Example550e8400-e29b-41d4-a716-446655440000

error object

Error details returned for a failed request.

ShowHide 4 properties

error.code string

Stable machine-readable error or resource code.

Exampleinvalid_input

error.message string

Human-readable explanation of the result or error.

ExampleThe request could not be validated.

error.requestId string

Correlation identifier for support and request tracing.

Example550e8400-e29b-41d4-a716-446655440000

error.details object nullable

Additional structured details about the result or error.

ShowHide 1 property

error.details.issues object[]

Structured field issues returned when request validation fails.

ShowHide 3 properties

error.details.issues[].path string | number[]

Field path where the validation issue occurred.

One of: string alternative 1, number alternative 2

Example0 items

error.details.issues[].reason string

Machine-readable reason for the validation issue.

Allowed values: "expected_type", "required", "unexpected_property", "invalid_value", "invalid_json", "invalid_query", "unsupported_media_type", "body_too_large", "body_timeout", "conflicting_scope", "missing_header", "concurrency_required", "invalid_resource_id", "invalid_request"

Exampleinvalid_request

error.details.issues[].code string nullable

Stable machine-readable error or resource code.

Exampleinvalid_input

{
  "error": {
    "code": "invalid_input",
    "message": "The request could not be validated.",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "details": {
      "issues": [
        {
          "path": [],
          "reason": "invalid_request"
        }
      ]
    }
  }
}

View raw OpenAPI operation

Use the machine-readable contract for client generation and payload validation.

Open OpenAPI contract ↗

curl --include --fail-with-body --request PUT "${NQD_API_URL:-http://api.nqd.localhost:1335}/v1/contacts" \ -H "Authorization: Bearer $NQD_API_KEY" \ -H "Workspace-Id: $NQD_WORKSPACE_ID" \ -H "Content-Type: application/json" \ --data '[ { "name": "NQD record", "description": "Consulting services for January 2026", "id": "01JQ2T5Y5Q3R8W9N6M4K2H7P1E" } ]'

{ "data": [ { "id": "01JQ2T5Y5Q3R8W9N6M4K2H7P1E", "clientId": null, "vendorId": null, "name": "NQD record", "description": "Consulting services for January 2026", "email": [ "owner@example.com" ], "phone": [ "+966500000000" ], "website": [ "https://example.com/hooks/nqd" ], "position": [ "Consulting services" ], "bankName": "NQD Bank", "iban": "SA0380000000608010167519", "notes": "Consulting services", "createdAt": "2026-01-15T12:00:00.000Z", "updatedAt": "2026-01-15T12:00:00.000Z" } ] }