Contacts

The people you send to. Most integrations identify them by externalId, the id your own system already uses.

Create or update a Contact by your own id

PUT /v1/contacts/{externalId}

Creates the Contact the first time you send its externalId and updates it on every later call. Answers 201 when it created the Contact and 200 when it updated one.

Requires the contacts:write scope.

Request body

Field	Type	Required
email	string	Required
name	string	Optional
phone	string	Optional
timeZone	string	Optional

Responses

• 200 OK: id, externalId, email, name, phone, timeZone, createdAt, updatedAt
• 201 Created: id, externalId, email, name, phone, timeZone, createdAt, updatedAt
• 400 Bad Request: code, message
• 402 Payment Required
• 403 Forbidden: code, message
• 429 Too Many Requests: code, message

Example

curl -X PUT https://server.api.throughline.dk/v1/contacts/user-42 \
  -H "Authorization: Bearer $THROUGHLINE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "ada@example.com",
  "name": "Ada Lovelace",
  "phone": "+4512345678",
  "timeZone": "Europe/Copenhagen"
}'

Read a Contact by your own id

GET /v1/contacts/{externalId}

Returns the Contact you created with this externalId, or 404 when there is none.

Requires the contacts:read scope.

Responses

• 200 OK: id, externalId, email, name, phone, timeZone, createdAt, updatedAt
• 403 Forbidden: code, message
• 404 Not Found
• 429 Too Many Requests: code, message

Example

curl -X GET https://server.api.throughline.dk/v1/contacts/user-42 \
  -H "Authorization: Bearer $THROUGHLINE_TOKEN"

Create or update a Contact by email

POST /v1/contacts

For systems that know a person only by email address. A Contact created this way has no externalId.

Requires the contacts:write scope.

Request body

Field	Type	Required
email	string	Required
name	string	Optional
phone	string	Optional
timeZone	string	Optional

Responses

• 200 OK: id, externalId, email, name, phone, timeZone, createdAt, updatedAt
• 201 Created: id, externalId, email, name, phone, timeZone, createdAt, updatedAt
• 400 Bad Request: code, message
• 402 Payment Required
• 403 Forbidden: code, message
• 429 Too Many Requests: code, message

Example

curl -X POST https://server.api.throughline.dk/v1/contacts \
  -H "Authorization: Bearer $THROUGHLINE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "ada@example.com",
  "name": "Ada Lovelace",
  "phone": "+4512345678",
  "timeZone": "Europe/Copenhagen"
}'

Read a Contact by Throughline id

GET /v1/contacts/by-id/{id}

Returns the Contact with this Throughline id, or 404 when there is none.

Requires the contacts:read scope.

Responses

• 200 OK: id, externalId, email, name, phone, timeZone, createdAt, updatedAt
• 403 Forbidden: code, message
• 404 Not Found
• 429 Too Many Requests: code, message

Example

curl -X GET https://server.api.throughline.dk/v1/contacts/by-id/0192f5a4-3c1e-7d2a-9b7e-1f2a3b4c5d6e \
  -H "Authorization: Bearer $THROUGHLINE_TOKEN"

Export everything held about a Contact

GET /v1/contacts/{externalId}/export

Everything Throughline holds about the Contact as a JSON Lines file, for answering a GDPR access request.

Requires the contacts:export scope.

Responses

• 200 OK
• 403 Forbidden: code, message
• 404 Not Found
• 429 Too Many Requests: code, message

Example

curl -X GET https://server.api.throughline.dk/v1/contacts/user-42/export \
  -H "Authorization: Bearer $THROUGHLINE_TOKEN"

Erase a Contact

POST /v1/contacts/{externalId}/erase

Permanently erases the Contact and their personal data, for answering a GDPR erasure request. It cannot be undone.

Requires the contacts:erase scope.

Responses

• 204 No Content
• 403 Forbidden: code, message
• 404 Not Found
• 429 Too Many Requests: code, message

Example

curl -X POST https://server.api.throughline.dk/v1/contacts/user-42/erase \
  -H "Authorization: Bearer $THROUGHLINE_TOKEN"

Export everything held about a Contact by Throughline id

GET /v1/contacts/by-id/{id}/export

The same export, for a Contact you created by email alone and so know only by the id the upsert returned.

Requires the contacts:export scope.

Responses

• 200 OK
• 403 Forbidden: code, message
• 404 Not Found
• 429 Too Many Requests: code, message

Example

curl -X GET https://server.api.throughline.dk/v1/contacts/by-id/0192f5a4-3c1e-7d2a-9b7e-1f2a3b4c5d6e/export \
  -H "Authorization: Bearer $THROUGHLINE_TOKEN"

Erase a Contact by Throughline id

POST /v1/contacts/by-id/{id}/erase

The same erasure, for a Contact you created by email alone and so know only by the id the upsert returned. Answers 204 again on a retry, and 404 only for an id that never named a Contact in your Tenant.

Requires the contacts:erase scope.

Responses

• 204 No Content
• 403 Forbidden: code, message
• 404 Not Found
• 429 Too Many Requests: code, message

Example

curl -X POST https://server.api.throughline.dk/v1/contacts/by-id/0192f5a4-3c1e-7d2a-9b7e-1f2a3b4c5d6e/erase \
  -H "Authorization: Bearer $THROUGHLINE_TOKEN"