Create or update a contact
const url = 'https://api.sendwing.app/api/organizations/example/contacts';const options = { method: 'PUT', headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'}, body: '{"email":"example","externalId":"example","firstName":"example","lastName":"example","status":"subscribed","language":"example","timeZone":"example","country":"example","birthday":"example","notes":"example","properties":{"additionalProperty":"example"},"tags":["example"],"mailingLists":["example"],"source":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PUT \ --url https://api.sendwing.app/api/organizations/example/contacts \ --header 'Content-Type: application/json' \ --header 'x-api-key: <x-api-key>' \ --data '{ "email": "example", "externalId": "example", "firstName": "example", "lastName": "example", "status": "subscribed", "language": "example", "timeZone": "example", "country": "example", "birthday": "example", "notes": "example", "properties": { "additionalProperty": "example" }, "tags": [ "example" ], "mailingLists": [ "example" ], "source": "example" }'Matches the contact by externalId when you send one, else by email, so it can also change a contact’s email. Fields you leave out keep their value, and null clears one. Unknown fields are refused.
tags are added by name: a name that isn’t a tag yet creates one, which needs the tag: create permission too. mailingLists subscribes the contact to lists by ID; lists it’s on stay as they are.
Consent is enforced: a contact who unsubscribed themselves can only be subscribed again by themselves, and asking for it is refused with a 409.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The workspace, like org_…. An OAuth access token works in the one the member picked when connecting, which GET /me returns.
Request Bodyrequired
Section titled “Request Bodyrequired”object
Matched ignoring case
Whether to email the contact. New contacts start as subscribed. Only subscribe people who agreed to get email.
An ISO 3166-1 alpha-2 code, like DE
YYYY-MM-DD, or --MM-DD when you don’t know the year, like 1990-05-14 or --05-14
Tags to add, by name, ignoring case. The contact keeps the tags it has. A new name creates a tag, which also needs the tag: create permission.
Mailing lists to subscribe the contact to, by ID. Lists it’s on stay as they are. The contact must be subscribed.
Where the contact came from, like checkout or zapier. Kept only when the contact is created.
Responses
Section titled “Responses”Updated
object
Like con_…
The contact’s ID in your own system
Whether Sendwing emails the contact. pending waits for double opt-in; bounced and complained are set by delivery feedback and are never emailed again.
Where the contact came from, like api, import, form or zapier
A BCP 47 language tag, like en or pt-BR
An IANA time zone, like Europe/Berlin
An ISO 3166-1 alpha-2 code, like DE
YYYY-MM-DD, or --MM-DD when the year isn’t known
Custom property values, by property key
object
object
object
Example
{ "status": "subscribed", "mailingLists": [ { "status": "subscribed" } ]}Created
object
Like con_…
The contact’s ID in your own system
Whether Sendwing emails the contact. pending waits for double opt-in; bounced and complained are set by delivery feedback and are never emailed again.
Where the contact came from, like api, import, form or zapier
A BCP 47 language tag, like en or pt-BR
An IANA time zone, like Europe/Berlin
An ISO 3166-1 alpha-2 code, like DE
YYYY-MM-DD, or --MM-DD when the year isn’t known
Custom property values, by property key
object
object
object
Example
{ "status": "subscribed", "mailingLists": [ { "status": "subscribed" } ]}The request isn’t valid; issues lists each problem
object
What went wrong, in words you can show people
For a 400: each invalid field, by its path in the request, like events.0.name
object
For a 5xx: quote it when contacting support
Example generated
{ "error": "example", "issues": [ { "path": "example", "message": "example" } ], "requestId": "example"}The API key or access token is missing, invalid or expired
object
What went wrong, in words you can show people
For a 400: each invalid field, by its path in the request, like events.0.name
object
For a 5xx: quote it when contacting support
Example generated
{ "error": "example", "issues": [ { "path": "example", "message": "example" } ], "requestId": "example"}The workspace’s plan doesn’t allow this, like more contacts than it includes
object
What went wrong, in words you can show people
For a 400: each invalid field, by its path in the request, like events.0.name
object
For a 5xx: quote it when contacting support
Example generated
{ "error": "example", "issues": [ { "path": "example", "message": "example" } ], "requestId": "example"}The API key’s permissions, or the app’s scopes and the member’s role, don’t allow this
object
What went wrong, in words you can show people
For a 400: each invalid field, by its path in the request, like events.0.name
object
For a 5xx: quote it when contacting support
Example generated
{ "error": "example", "issues": [ { "path": "example", "message": "example" } ], "requestId": "example"}Not found in this workspace
object
What went wrong, in words you can show people
For a 400: each invalid field, by its path in the request, like events.0.name
object
For a 5xx: quote it when contacting support
Example generated
{ "error": "example", "issues": [ { "path": "example", "message": "example" } ], "requestId": "example"}Conflicts with the current state; error says how
object
What went wrong, in words you can show people
For a 400: each invalid field, by its path in the request, like events.0.name
object
For a 5xx: quote it when contacting support
Example generated
{ "error": "example", "issues": [ { "path": "example", "message": "example" } ], "requestId": "example"}Too many requests; wait for the seconds in Retry-After
object
What went wrong, in words you can show people
For a 400: each invalid field, by its path in the request, like events.0.name
object
For a 5xx: quote it when contacting support
Example generated
{ "error": "example", "issues": [ { "path": "example", "message": "example" } ], "requestId": "example"}