Contacts

Create or update contacts in a batch

POST/v1/contacts/batch

Requires an API key with the contacts:write scope. About keys and scopes

Identify for up to 100 contacts in one request, each resolved and written exactly as POST /v1/contacts/identify would, in order. One contact refused does not stop the rest: its entry carries the error a single identify would have answered. Counts against the rate limit as one request per contact; for a larger sync, send several batches. Agent keys are refused with 403.

Request body

contactsCreateContactInput[]required

at least 1 item · at most 100 items

12 child attributes

externalIdstring | nulloptional

Your own id for the contact, up to 255 characters. Identify matches on it first.

1–255 characters

emailstring | nulloptional

firstNamestring | nulloptional

1–100 characters

lastNamestring | nulloptional

1–100 characters

phonestring | nulloptional

Phone number; normalised to E.164 (a leading + and country code).

timezonestring | nulloptional

IANA timezone, e.g. Europe/London; used for send-time scheduling.

up to 100 characters

countrystring | nulloptional

ISO 3166-1 alpha-2 code. Omitted, it is inferred from the phone, else the timezone.

datesContactDatesInputoptional

Named calendar dates, merged key by key; null removes one.

attributesobjectoptional

Custom attributes, merged key by key; null removes one. At most 50 keys and 16 KB.

emailConsentbooleanoptional

Consent to email. Omitted, the current value is kept.

pushConsentbooleanoptional

Consent to push. Omitted, the current value is kept.

consentStatementConsentStatementInputoptional

How the contact agreed, recorded with any consent this request grants.

2 child attributes

basisstringrequired

The legal basis the contacts agreed under.

one of opted_in, existing_customer

evidencestringrequired

Where and how they agreed, e.g. "Checkout opt-in on shop.example.com".

1–500 characters

Returns

Returns 200 OK with a IdentifyContactsBatchResult in data. Otherwise returns an error; Errors lists every code and which to retry.

resultsobject[]required

One of 2 shapes

Contact written

2 child attributes

createdbooleanrequired

Whether a new contact was created.

contactContactDetailrequired

15 child attributes

idstringrequired

uuid

externalIdstring | nullrequired

Your own id for the contact, if set.

emailstring | nullrequired

firstNamestring | nullrequired

lastNamestring | nullrequired

phonestring | nullrequired

Phone number in E.164 format.

timezonestring | nullrequired

IANA timezone, e.g. Europe/London.

countrystring | nullrequired

ISO 3166-1 alpha-2 code: as written, or inferred from the phone, else the timezone.

datesobjectrequired

Named calendar dates, e.g. birthday, as YYYY-MM-DD or --MM-DD.

attributesobjectrequired

Custom attributes, keyed by attribute name.

emailConsentbooleanrequired

Whether the contact has consented to email.

pushConsentbooleanrequired

Whether the contact has consented to push.

createdAtstringrequired

date-time

updatedAtstringrequired

date-time

emailSuppressionobjectrequired

2 child attributes

suppressedbooleanrequired: Whether email to this contact is blocked.
reasonstring | nullrequired: Why email to this contact is suppressed: bounced, complained, complained_transactional, unsubscribed, manual, imported, or other_workspace (a bounce or complaint in another workspace with the same owner or partner).

Contact refused

1 child attribute

errorobjectrequired

4 child attributes

codestringrequired: one of BAD_REQUEST, ALREADY_EXISTS, CONFLICT, IN_USE, FORBIDDEN, INTERNAL_ERROR, NOT_FOUND, RATE_LIMITED, REVISION_CONFLICT, SERVICE_UNAVAILABLE, UNAUTHORIZED, VALIDATION_ERROR, API_KEY_IP_NOT_ALLOWED, AGENT_CONFIRMATION_REQUIRED, EMBED_ORIGIN_NOT_ALLOWED, WORKSPACE_SUSPENDED, WORKSPACE_DELETION_PENDING, CONTACT_SEND_IN_PROGRESS, EXPORT_UNAVAILABLE, NOTHING_TO_EXPORT, EVENT_NAME_LIMIT_REACHED, PLAN_LIMIT_REACHED, PLAN_FEATURE_UNAVAILABLE, CAMPAIGN_AUDIENCE_CONFLICT, EMPTY_AUDIENCE, INVALID_CAMPAIGN_CONTENT, DRAFT_INCOMPLETE, INVALID_SCHEDULE, UNSUPPORTED_CHANNEL, POSTAL_ADDRESS_MISSING, CONSENT_MISSING, SUPPRESSED, SIGNUP_BLOCKED, INVALID_SENDER_ADDRESS, SENDING_DOMAIN_DMARC_MISSING, SENDING_DOMAIN_IDENTITY_CONFLICT, SENDING_DOMAIN_UNVERIFIED, IDEMPOTENCY_KEY_REUSED, CONTENT_NOT_RETAINED, RECIPIENT_EMAIL_MISSING, TEMPLATE_NOT_PUBLISHED, TEMPLATE_ENVELOPE_INCOMPLETE, PUSH_APP_NOT_READY, PUSH_DESTINATION_MISSING
messagestringrequired
detailsobjectoptional
requestIdstringoptional

curl -X POST https://api.kirora.io/v1/contacts/batch \
  -H "Authorization: Bearer $KIRORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {}
    ]
  }'

const response = await fetch('https://api.kirora.io/v1/contacts/batch', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "contacts": [
      {}
    ]
  }),
});
const { data } = await response.json();

import os

import requests

response = requests.post(
    "https://api.kirora.io/v1/contacts/batch",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
    json={
        "contacts": [
            {},
        ],
    },
)
data = response.json()["data"]

package main

import (
	"bytes"
	"encoding/json"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
	  "contacts": [
	    {}
	  ]
	}`)
	req, err := http.NewRequest("POST", "https://api.kirora.io/v1/contacts/batch", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var out struct {
		Data json.RawMessage `json:"data"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		panic(err)
	}
}

Response · 200

{
  "data": {
    "results": [
      {
        "created": true,
        "contact": {
          "id": "018f2a4e-6b1c-7d3e-9f40-37386ae05a6b",
          "externalId": "user_8812",
          "email": "amaka@juniperkitchen.com",
          "firstName": "Amaka",
          "lastName": "Eze",
          "phone": "+447700900123",
          "timezone": "Europe/London",
          "country": "GB",
          "dates": {},
          "attributes": {},
          "emailConsent": true,
          "pushConsent": true,
          "createdAt": "2030-03-14T09:30:00Z",
          "updatedAt": "2030-03-14T09:30:00Z",
          "emailSuppression": {
            "suppressed": null,
            "reason": null
          }
        }
      }
    ]
  }
}

Example values are generated from the schema.