API reference

Cardholder identities

The people a card program names, by its own id for them, and the member of the books each one is.

GET/v1/cardholder_identitiesList the people card programs name
POST/v1/cardholder_identitiesAdd a person a card program names
GET/v1/cardholder_identities/{identity_id}Get a person a card program names
PATCH/v1/cardholder_identities/{identity_id}Link a card program's person to a member
DELETE/v1/cardholder_identities/{identity_id}Forget a person a card program names
POST/v1/cardholder_identities/{identity_id}/claimSay a card program's person is you
POST/v1/cardholder_identities/{identity_id}/not_meSay a card program's person is not you
DELETE/v1/cardholder_identities/{identity_id}/not_meTake back saying a card program's person is not you

Guides: Get missing receipts from cardholders

List the people card programs name

GET/v1/cardholder_identities

client.cardholderIdentities.list()

The people the card programs name, newest first, each with the member of these books they are when that is known.

Parameters

Name	Type	Description
`source`Query	string or null	Only this card program's people.
`linked`Query	boolean or null	`true`: only those linked to a member; `false`: only those not.
`user_id`Query	string or null	An id that starts with `usr_`.
`suggested`Query	boolean	Only the people the caller might be and nobody has placed yet: what the Inbox asks them about once ("Is this you on Brex?"). One page, of at most `limit`. Default false
`limit`Query	integer	Page size, 1–200. Default 50
`cursor`Query	string or null	The `next_cursor` of the previous page.

Response

200CardholderIdentityPage

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl "https://api.ledgerit.ai/v1/cardholder_identities" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Add a person a card program names

POST/v1/cardholder_identities· Idempotent

client.cardholderIdentities.create()

Tell the books about a person a card program names before a sync has, by the program's id for them, and which member they are. A sync adds every person it sees on its own; one the books know already is refused (409).

Request body

CardholderIdentityCreate

Response

201CardholderIdentityOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X POST "https://api.ledgerit.ai/v1/cardholder_identities" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"source":"…","source_ref":"…"}'

Get a person a card program names

GET/v1/cardholder_identities/{identity_id}

client.cardholderIdentities.get()

One person a card program names, and the member they are.

Parameters

Name	Type	Description
`identity_id`Path · Required	string	An id that starts with `cardholder_identity_`.

Response

200CardholderIdentityOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl "https://api.ledgerit.ai/v1/cardholder_identities/{identity_id}" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Link a card program's person to a member

PATCH/v1/cardholder_identities/{identity_id}

client.cardholderIdentities.update()

Say which member a person is (user_id), or that the books do not know (null). Their open missing receipts go to that member, who uploads them in the app. A name or address given here stands until the card program says otherwise.

Parameters

Name	Type	Description
`identity_id`Path · Required	string	An id that starts with `cardholder_identity_`.

Request body

CardholderIdentityUpdate

Response

200CardholderIdentityOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X PATCH "https://api.ledgerit.ai/v1/cardholder_identities/{identity_id}" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Forget a person a card program names

DELETE/v1/cardholder_identities/{identity_id}

client.cardholderIdentities.delete()

Forget a person and their link. The next sync that sees them named knows them again by name and address, without the link.

Parameters

Name	Type	Description
`identity_id`Path · Required	string	An id that starts with `cardholder_identity_`.

Response

204No content

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X DELETE "https://api.ledgerit.ai/v1/cardholder_identities/{identity_id}" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Say a card program's person is you

POST/v1/cardholder_identities/{identity_id}/claim

client.cardholderIdentities.claim()

"It's me": the caller says they are this person. Kept for good, so they are not asked again, and their missing receipts become theirs to upload. Claiming again changes nothing; a person someone else claimed is refused (409). A "Not me" the caller said about them is taken back.

Parameters

Name	Type	Description
`identity_id`Path · Required	string	An id that starts with `cardholder_identity_`.

Response

200CardholderIdentityOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X POST "https://api.ledgerit.ai/v1/cardholder_identities/{identity_id}/claim" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Say a card program's person is not you

POST/v1/cardholder_identities/{identity_id}/not_me

client.cardholderIdentities.notMe()

"Not me": the caller says they are not this person. Kept for good, so they are not asked about them again; saying it twice changes nothing. A link to the caller is taken back. The person's missing receipts go on to whoever else might be them, or to the founder, who is asked for an address. DELETE on the same path takes it back.

Parameters

Name	Type	Description
`identity_id`Path · Required	string	An id that starts with `cardholder_identity_`.

Response

200CardholderIdentityOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X POST "https://api.ledgerit.ai/v1/cardholder_identities/{identity_id}/not_me" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Take back saying a card program's person is not you

DELETE/v1/cardholder_identities/{identity_id}/not_me

client.cardholderIdentities.undoNotMe()

Take back the caller's "Not me" about this person: they may be asked "Is this you?" again. Taking back one never said changes nothing.

Parameters

Name	Type	Description
`identity_id`Path · Required	string	An id that starts with `cardholder_identity_`.

Response

200CardholderIdentityOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X DELETE "https://api.ledgerit.ai/v1/cardholder_identities/{identity_id}/not_me" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Objects

The objects these operations take and return.

CardholderIdentityPage

Name	Type	Description
`data`Required	array of CardholderIdentityOut
`has_more`Required	boolean
`next_cursor`Required	string or null

CardholderIdentityCreate

Name	Type	Description
`email`	string or null
`name`	string or null
`source`Required	string	The card program: `brex`, `ramp`.
`source_ref`Required	string	The card program's own id for the person.
`user_id`	string or null	An id that starts with `usr_`.

CardholderIdentityOut

Name	Type	Description
`connection_id`Required	string or null	An id that starts with `conn_`.
`created_at`Required	string (date-time)
`email`Required	string or null	Their address, as the card program gives it. Null when it gives none, or the connection may not read its people.
`fetched_at`Required	string (date-time) or null	When the card program's directory was last read for them; null when only a charge named them.
`id`Required	string	An id that starts with `cardholder_identity_`.
`last_seen_at`Required	string (date-time)	When a sync last saw them named.
`linked_at`Required	string (date-time) or null	When they were linked to a member.
`linked_by`Required	string or null	An id that starts with `usr_`.
`name`Required	string or null	Their name, as the card program gives it.
`not_me`Required	array of string	The members who said this person is not them ("Not me"), in the order they said it. None of them is asked about the person again.
`payload`Required	object	What the card program said about the person, whole and verbatim: every id and field.
`source`Required	string	The card program that names them: `brex`, `ramp`.
`source_ref`Required	string	The card program's own id for the person.
`user_id`Required	string or null	An id that starts with `usr_`.

CardholderIdentityUpdate

Name	Type	Description
`email`	string or null
`name`	string or null
`user_id`	string or null	An id that starts with `usr_`.