Create contact

POST/api/v1/contacts

A new contact in the workspace. If the address already exists, the response is 409 contact_exists.

consent_source is the proof of consent and is required. Contact fields that are mandatory in the workspace must be included in fields.

To create or update in the same call: use POST /contacts/upsert.

Scope

contacts:write Edit contacts – the person behind the key must be editor or higher.

Body

JSON, Content-Type: application/json. Unknown fields return 422.

emailstringrequired: The email address.at most 254 characters
first_namestring | null: First name.at most 100 characters
last_namestring | null: Last name.at most 100 characters
companystring | null: Company.at most 200 characters
phonestring | null: Phone number. Without a country code, it is interpreted according to the workspace's country.at most 50 characters
fieldsobject<string | number | boolean>: Custom fields by key (GET /fields). The values are checked against the field's type. null or "" removes a value. Keys that are not fields in the workspace are saved as free-form fields. Sensitive fields (personal identity numbers) cannot be set via the API.
tagsarray<string>: Tags.at most 50
consent_sourcestringrequired: How the person consented to mailings, in your own words. Saved as proof.at least 3 characters · at most 255 characters
list_idsarray<string>: Lists to add the contact to directly (as when a person adds a contact in the app).at most 100

Retrying a request

Feel free to send the Idempotency-Key header (e.g. a UUID). If the same request is sent again with the same key within 24 hours, the first response is returned, without anything being done twice. Batch and idempotency

Response

201 The new contact.

idstringrequired: The contact's ID.
emailstringrequired: The email address (lower case). Never changes: consents and suppressions apply to the address.
first_namestring | nullrequired
last_namestring | nullrequired
companystring | nullrequired
phonestring | nullrequired: In international format (E.164), e.g. +46701234567.
statusstringrequired: active: can receive mailings · unsubscribed: has unsubscribed from everything · bounced: the address bounces · complained: has reported spam · deleted: erased (GDPR), the personal data is gone.activeunsubscribedbouncedcomplaineddeleted
fieldsobject<string | number | boolean>required: Custom fields by key (see GET /fields). Sensitive fields, such as personal identity numbers, are never sent out.
tagsarray<string>required
sourcestringrequired: How the contact was added: manual, import, form, api …
consentobjectrequired
consent.atstring (time, ISO 8601) | nullrequired: When consent was given.
consent.sourcestring | nullrequired: How the person consented, in your own words.
suppressionobject | nullrequired: The workspace's suppression of the address. A suppressed address never receives mailings, regardless of status.
suppression.reasonstringrequired: unsubscribed, bounced, complained, manual or imported.
suppression.created_atstring (time, ISO 8601)required: When the address was suppressed.
sharedbooleanrequired: Shared from a level above in the organisation: can be read and receive mailings from here, but can only be changed where it belongs.
created_atstring (time, ISO 8601)required: When the contact was created.
updated_atstring (time, ISO 8601)required: When the contact was last changed.
unsubscribed_atstring (time, ISO 8601) | nullrequired: When the person unsubscribed.
listsarray<object>required: The workspace's lists that the contact is on. Empty for a shared contact.
lists[].list_idstringrequired
lists[].namestringrequired
lists[].statusstringrequired: subscribed: on the list · pending: waiting to confirm by email · unsubscribed: has left the list.subscribedpendingunsubscribed
lists[].subscribed_atstring (time, ISO 8601) | nullrequired: When the person joined the list.

Errors

400: bad_request
401: unauthenticated invalid_key key_revoked key_expired key_inactive
402: payment_required
403: insufficient_scope forbidden workspace_suspended
409: contact_exists suppressed idempotency_in_progress
415: unsupported_media_type
422: validation_failed idempotency_key_reused
429: rate_limited
500: internal_error

Request

curl -X POST 'https://newsletter.qrona.se/api/v1/contacts' \
  -H "Authorization: Bearer $QRONA_NEWSLETTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"anna@example.se","first_name":"Anna","last_name":"Svensson","fields":{"kundnummer":"K-2041"},"tags":["kund"],"consent_source":"Ticked the box at checkout on butik.se"}'

Response 201

{
  "id": "1042",
  "email": "anna@example.se",
  "first_name": "Anna",
  "last_name": "Svensson",
  "company": "Example Ltd",
  "phone": "+46701234567",
  "status": "active",
  "fields": {
    "kundnummer": "K-2041",
    "ort": "Göteborg"
  },
  "tags": [
    "kund",
    "vip"
  ],
  "source": "api",
  "consent": {
    "at": "2026-10-19T08:30:00.000Z",
    "source": "Ticked the box at checkout on butik.se"
  },
  "suppression": null,
  "shared": false,
  "created_at": "2026-10-19T08:30:00.000Z",
  "updated_at": "2026-10-19T08:30:00.000Z",
  "unsubscribed_at": null,
  "lists": [
    {
      "list_id": "3f1c2a4e-8b7d-4c1e-9f0a-2d6b5e7c8a91",
      "name": "Nyhetsbrev",
      "status": "subscribed",
      "subscribed_at": "2026-10-19T08:30:00.000Z"
    }
  ]
}