Skapa eller uppdatera kontakt

POST/api/v1/contacts/upsert

Skapar kontakten om adressen är ny, annars uppdateras den. Det vanliga anropet för en integration.

Svarar 201 när kontakten skapades och 200 när den uppdaterades. Bara de fält du skickar ändras. add_tags/remove_tags ändrar taggar utan att röra de andra.

consent_source krävs när kontakten skapas. Adressen skickas i kroppen, aldrig i adressraden, så att den inte hamnar i loggar.

Listmedlemskap ändras inte här: anmäl till en lista med POST /lists/{id}/members.

Behörighet

contacts:write Ändra kontakter – personen bakom nyckeln måste vara redaktör eller högre.

Kropp

JSON, Content-Type: application/json. Okända fält ger 422.

emailstringkrävs: E-postadressen.högst 254 tecken
first_namestring | null: Förnamn.högst 100 tecken
last_namestring | null: Efternamn.högst 100 tecken
companystring | null: Företag.högst 200 tecken
phonestring | null: Telefonnummer. Utan landsnummer tolkas det enligt arbetsytans land.högst 50 tecken
fieldsobject<string | number | boolean>: Egna fält efter nyckel (GET /fields). Värdena kontrolleras mot fältets typ. null eller "" tar bort ett värde. Nycklar som inte är fält i arbetsytan sparas som fria fält. Känsliga fält (personnummer) kan inte sättas via API:t.
tagsarray<string>: Ersätter alla taggar. Använd inte tillsammans med add_tags/remove_tags.högst 50 st
add_tagsarray<string>: Taggar att lägga till; de andra behålls.högst 50 st
remove_tagsarray<string>: Taggar att ta bort.högst 50 st
consent_sourcestring: Hur personen samtyckte. Krävs när kontakten skapas; ändrar inget på en befintlig kontakt.minst 3 tecken · högst 255 tecken

Göra om anropet

Skicka gärna headern Idempotency-Key (t.ex. ett uuid). Skickas samma anrop igen med samma nyckel inom 24 timmar kommer det första svaret tillbaka, utan att något görs två gånger. Batch och idempotens

Svar

200 Kontakten (201 om den skapades).

idstringkrävs: Kontaktens id.
emailstringkrävs: E-postadressen (gemener). Ändras aldrig: samtycken och spärrar gäller adressen.
first_namestring | nullkrävs
last_namestring | nullkrävs
companystring | nullkrävs
phonestring | nullkrävs: I internationellt format (E.164), t.ex. +46701234567.
statusstringkrävs: active: kan få utskick · unsubscribed: har avregistrerat sig från allt · bounced: adressen studsar · complained: har anmält skräppost · deleted: raderad (GDPR), personuppgifterna är borta.activeunsubscribedbouncedcomplaineddeleted
fieldsobject<string | number | boolean>krävs: Egna fält efter nyckel (se GET /fields). Känsliga fält, som personnummer, skickas aldrig ut.
tagsarray<string>krävs
sourcestringkrävs: Hur kontakten kom in: manual, import, form, api …
consentobjectkrävs
consent.atstring (tid, ISO 8601) | nullkrävs: När samtycket gavs.
consent.sourcestring | nullkrävs: Hur personen samtyckte, med egna ord.
suppressionobject | nullkrävs: Arbetsytans spärr på adressen. En spärrad adress får aldrig utskick, oavsett status.
suppression.reasonstringkrävs: unsubscribed, bounced, complained, manual eller imported.
suppression.created_atstring (tid, ISO 8601)krävs: När adressen spärrades.
sharedbooleankrävs: Delad från en nivå ovanför i organisationen: kan läsas och få utskick härifrån, men bara ändras där den hör hemma.
created_atstring (tid, ISO 8601)krävs: När kontakten skapades.
updated_atstring (tid, ISO 8601)krävs: När kontakten senast ändrades.
unsubscribed_atstring (tid, ISO 8601) | nullkrävs: När personen avregistrerade sig.
listsarray<object>krävs: Arbetsytans listor som kontakten finns på. Tom för en delad kontakt.
lists[].list_idstringkrävs
lists[].namestringkrävs
lists[].statusstringkrävs: subscribed: med på listan · pending: väntar på att bekräfta via e-post · unsubscribed: har lämnat listan.subscribedpendingunsubscribed
lists[].subscribed_atstring (tid, ISO 8601) | nullkrävs: När personen kom med på listan.

Fel

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

Anrop

curl -X POST 'https://newsletter.qrona.se/api/v1/contacts/upsert' \
  -H "Authorization: Bearer $QRONA_NEWSLETTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"anna@example.se","first_name":"Anna","fields":{"kundnummer":"K-2041"},"add_tags":["kund"],"consent_source":"Kryssade i rutan i kassan på butik.se"}'

Svar 200

{
  "id": "1042",
  "email": "anna@example.se",
  "first_name": "Anna",
  "last_name": "Svensson",
  "company": "Exempel AB",
  "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": "Kryssade i rutan i kassan på 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"
    }
  ]
}