Create a new contact

POST

/contacts

curl --request POST \
  --url https://app.surveyrock.com/api/v1/contacts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --data '{ "email": "hello@example.com", "first_name": "example", "last_name": "example", "customFields": {} }'

• API v1 endpoints

Create a new contact. The response carries the new resource’s ETag, as the ETag header and as meta.etag.

Authorizations

• bearerAuth
  contacts:write

Parameters

Header Parameters

Idempotency-Key

required

string

>= 1 characters <= 128 characters

1 to 128 characters, chosen by the caller. A retry with the same key and body replays the first response instead of applying the write twice; the same key with a different body is a 409

Request Body^required

Media typeapplication/json

object

email

required

string format: email

first_name

string

last_name

string

customFields

Values keyed by the id of one of the workspace’s custom fields; an id that is not one is a 422

object

Example^generated

{
  "email": "hello@example.com",
  "first_name": "example",
  "last_name": "example",
  "customFields": {}
}

Responses

201

Contact created. When the email belongs to a deleted contact, that contact is restored (same id) with the new name and fields and no list memberships; it keeps an Unsubscribed, Hard Bounced or Complained status, so check status.

Headers

ETag

string

Example

"element:abc123:1790690123456789"

The resource’s current version, as a strong validator. Opaque: send it back unchanged as If-Match. Also returned as meta.etag in the body, for a client that only sees the body.

409

Duplicate email

422

The request is malformed, or a customFields key is not a custom field of this workspace: each error names the field