Recipient matching

Use recipient matching to check which recipients are eligible to receive content from a specific tenant. Each request contains a list of recipient identifiers, and the response is a filtered list containing only the identifiers eligible to receive content from that tenant.

Recipients who have opted out from the tenant are excluded. If none of the provided identifiers are eligible, Kivra returns an empty list.

Match by SSN

Match a list of recipient SSNs with:

POST /v2/tenant/{tenantKey}/usermatch/ssn

The payload can be up to 10 MB, corresponding to about 500,000 SSNs. If the payload exceeds 10 MB, Kivra responds with 413.

{
  "list": [
    "191212121212",
    "197701032380",
    "198112172385"
  ]
}

The response contains only the SSNs that matched:

{
  "list": [
    "191212121212",
    "198112172385"
  ]
}

See the Match Users SSN API reference for the complete request and response schema.

Match by verified email

Match a list of recipient email addresses with:

POST /v2/tenant/{tenantKey}/usermatch/verified_email

The payload can be up to 10 MB. If the payload exceeds 10 MB, Kivra responds with 413. Email matching is case insensitive, but the queried email case is returned as submitted.

{
  "list": [
    "fOO@example.com",
    "bAr@EXAMPLE.COM",
    "XYZ@example.COM"
  ]
}

The response contains only the email addresses that matched:

{
  "list": [
    "fOO@example.COM",
    "bAr@EXAMPLE.COM"
  ]
}

See the Match Users verified email API reference for the complete request and response schema.

Match by VAT number

Match a list of recipient company VAT numbers with:

POST /v2/tenant/{tenantKey}/companymatch/vatnr

The payload can be up to 10 MB, corresponding to about 500,000 VAT numbers. If the payload exceeds 10 MB, Kivra responds with 413.

{
  "list": [
    "SE559408724801",
    "SE556917354401",
    "SE556840226601"
  ]
}

The response contains only the VAT numbers that matched:

{
  "list": [
    "SE559408724801",
    "SE556840226601"
  ]
}

See the Match Companies VatNr API reference for the complete request and response schema.