Contacts

List contacts

GET/v1/contacts

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

Returns contacts in this organization. Filter by email to look up a single address; it is matched trimmed and without case. Filter by externalId to find the contact carrying your own id; it is matched exactly. Use q to search instead: it matches any part of the email address or name, ignoring case. consent, suppressed, groupId, segmentId and createdAfter narrow the list and combine with each other and with q; an unknown group or segment is a 404. Each item lists the groups it is in (groupIds). meta.total counts every contact matching the filters, up to 10000: beyond that it reports the cap and meta.totalExact is false; both are counted on the first page only (null with a cursor). Results are newest first and cursor-paginated: pass meta.pagination.nextCursor back as cursor until it comes back null. The cursor is opaque — do not construct or parse one.

Query parameters

limitintegeroptional

min > 0 · max 100 · default 20

cursorstringoptional

1–2048 characters

emailstringoptional

Exact match on the address, trimmed, without case.

qstringoptional

Searches any part of the email address or name, ignoring case.

1–100 characters

externalIdstringoptional

Your own id for the contact, as set with identify; matched exactly.

1–255 characters

consentstringoptional

Comma-separated channels, e.g. email,push: consent granted on each.

suppressedstringoptional

Whether email to the contact, or to its address, is suppressed.

one of true, false

groupIdstringoptional

Only members of this group.

uuid

segmentIdstringoptional

The segment's members as of its last background sweep.

uuid

createdAfterstringoptional

Created at or after this time.

date-time

Returns

Returns 200 OK with a list of ContactListItem objects in data, and the next page's cursor in meta (see pagination). Otherwise returns an error; Errors lists every code and which to retry.

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).

groupIdsstring[]required

Ids of the groups the contact is in.

curl https://api.kirora.io/v1/contacts \
  -H "Authorization: Bearer $KIRORA_API_KEY"

const response = await fetch('https://api.kirora.io/v1/contacts', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
  },
});
const { data } = await response.json();

import os

import requests

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

package main

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

func main() {
	req, err := http.NewRequest("GET", "https://api.kirora.io/v1/contacts", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))

	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": [
    {
      "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": true,
        "reason": "reason_example"
      },
      "groupIds": [
        "018f2a4e-6b1c-7d3e-9f40-b0a20d965a6b"
      ]
    }
  ],
  "meta": {
    "pagination": {
      "limit": 1,
      "nextCursor": "nextCursor_example"
    },
    "total": 0,
    "totalExact": true
  }
}

Example values are generated from the schema.