Subjects

Refer a person

POST https://api.xipid.org/subjects

Refers a person by the brand's own reference for them, which travels in the body alone, with one channel, the name the brand knows them by, and the scopes it asks them to grant. XipID invites them by email, or the brand delivers the subject's invite_url on its own channel; the subject is pending until they accept, and then carries the pairwise identifier a challenge names them by. The same reference again repeats the referral and answers the same subject while it is live; asking other scopes of a person who accepted is refused.

Scope: any live key of the brand.

Limits: 1,000 requests a minute per key and 2,000 requests a minute per source address; every answer says what is left in X-RateLimit-Remaining, and a refusal when to come back in Retry-After.

Idempotency: takes an Idempotency-Key, which it requires: a retry under the same key is answered what the first request was, for 24 hours, and the key sent with another request is refused.

Changes: 2026-09-26: added.

Parameters

Idempotency-Key a header, required, string, at most 512 characters
The operation's key, 1 to 255 characters, best a UUID, in double quotes as a structured field string: a retry of the operation sends it again, and is answered what the first request was, for 24 hours.
Xip-Version a header, optional, string, one of the values below
The version to answer in; when absent, the version the brand's org is pinned to.
- 2026-09-26: The first version: challenges, subjects and events, and the signed outcome.

Body

reference string, at most 128 characters
display_name string, at most 120 characters, optional
channel one of the shapes below
- One shape
  A phone number in E.164, which XipID never texts: the brand may deliver the invite_url on its own channel.
  - type always "phone"
  - to phone number, E.164
- One shape
  An email address, which XipID emails the invitation.
  - type always "email"
  - to email address, at most 254 characters
scopes array of object, at most 20 items
- attribute string, one of the values below
  What the scope lets the brand do with the person.
  - presence: Ask them to confirm it is really them, by a challenge.
  - name: See their name.
  - date_of_birth: See their date of birth.
  - email: See their email address.
  - phone: See their phone number.
  - address: See their address.
  - tier: See their verification tier.
  - ssn_match: Check that a Social Security number the brand holds is theirs.
- purpose string

{
  "reference": "acct_4417",
  "display_name": "Sam Rivera",
  "channel": {
    "type": "phone",
    "to": "+16195550142"
  },
  "scopes": [
    {
      "attribute": "presence",
      "purpose": "wire_approval"
    }
  ]
}

Answers

200 OK

The live subject the reference already names, its referral repeated.

Its headers: X-Request-Id, Xip-Version, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, ETag.

id ULID
reference string
status string, one of the values below
Where the referral stands for the brand; the last three are final.
- pending: Waiting on the person to accept.
- linked: The person accepted: the brand has their pairwise identifier and may challenge them.
- declined: The person declined. Final.
- expired: Unanswered for thirty days. Final.
- unlinked: The person took the brand's access back. Final.
pairwise_id pairwise identifier, optional
linked_at instant, RFC 3339, optional
invite_url URL, at most 2,048 characters, optional
display_name string, optional
channel object
- type string, one of the values below
  The channel the brand referred the person by.
  - phone: A phone number.
  - email: An email address.
- to_masked string, optional
scopes array of object
- attribute string, one of the values below
  What the scope lets the brand do with the person.
  - presence: Ask them to confirm it is really them, by a challenge.
  - name: See their name.
  - date_of_birth: See their date of birth.
  - email: See their email address.
  - phone: See their phone number.
  - address: See their address.
  - tier: See their verification tier.
  - ssn_match: Check that a Social Security number the brand holds is theirs.
- purpose string
reference_face object, optional
- enrolled_at instant, RFC 3339
created_at instant, RFC 3339
updated_at instant, RFC 3339

{
  "id": "01JD2R2B4D6F8H0J2K4M6N8P0Q",
  "reference": "acct_4417",
  "status": "pending",
  "invite_url": "https://app.xipid.org/invitations",
  "display_name": "Sam Rivera",
  "channel": {
    "type": "phone",
    "to_masked": "+1 ••• ••• 0142"
  },
  "scopes": [
    {
      "attribute": "presence",
      "purpose": "wire_approval"
    }
  ],
  "created_at": "2026-11-18T15:20:07.311Z",
  "updated_at": "2026-11-18T15:20:07.311Z"
}

201 Created

The subject the referral made. Location names it.

Its headers: X-Request-Id, Xip-Version, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Location, ETag.

id ULID
reference string
status string, one of the values below
Where the referral stands for the brand; the last three are final.
- pending: Waiting on the person to accept.
- linked: The person accepted: the brand has their pairwise identifier and may challenge them.
- declined: The person declined. Final.
- expired: Unanswered for thirty days. Final.
- unlinked: The person took the brand's access back. Final.
pairwise_id pairwise identifier, optional
linked_at instant, RFC 3339, optional
invite_url URL, at most 2,048 characters, optional
display_name string, optional
channel object
- type string, one of the values below
  The channel the brand referred the person by.
  - phone: A phone number.
  - email: An email address.
- to_masked string, optional
scopes array of object
- attribute string, one of the values below
  What the scope lets the brand do with the person.
  - presence: Ask them to confirm it is really them, by a challenge.
  - name: See their name.
  - date_of_birth: See their date of birth.
  - email: See their email address.
  - phone: See their phone number.
  - address: See their address.
  - tier: See their verification tier.
  - ssn_match: Check that a Social Security number the brand holds is theirs.
- purpose string
reference_face object, optional
- enrolled_at instant, RFC 3339
created_at instant, RFC 3339
updated_at instant, RFC 3339

{
  "id": "01JD2R2B4D6F8H0J2K4M6N8P0Q",
  "reference": "acct_4417",
  "status": "pending",
  "invite_url": "https://app.xipid.org/invitations",
  "display_name": "Sam Rivera",
  "channel": {
    "type": "phone",
    "to_masked": "+1 ••• ••• 0142"
  },
  "scopes": [
    {
      "attribute": "presence",
      "purpose": "wire_approval"
    }
  ],
  "created_at": "2026-11-18T15:20:07.311Z",
  "updated_at": "2026-11-18T15:20:07.311Z"
}

Errors

json_invalid, 400: The request body is not valid JSON.
parameter_missing, 400: The request lacks a required parameter.
parameter_invalid, 400: The request contains invalid parameters.
parameter_unknown, 400: The request contains a parameter this route does not take.
idempotency_key_missing, 400: This route requires an Idempotency-Key header.
version_invalid, 400: Xip-Version names no released version of this API.
authentication_required, 401: Authentication is required.
authentication_failed, 401: The credential is invalid, expired or revoked.
insufficient_scope, 403: The credential does not allow this operation.
idempotency_key_in_use, 409: The first request with this Idempotency-Key is still running.
subject_scopes_accepted, 409: The person accepted the scopes first asked, and asking for others needs their consent again.
content_too_large, 413: The request body is larger than this route accepts.
media_type_unsupported, 415: This route does not accept that Content-Type.
idempotency_key_reused, 422: This Idempotency-Key was used for a different request.
rate_limit_exceeded, 429: Too many requests; try again later.
internal_error, 500: Something went wrong on our side.
service_unavailable, 503: The service is temporarily unavailable.