API reference

Counterparty roles

What a counterparty is to the books: customer, vendor, employee, investor, lender or founder.

GET/v1/counterparties/{counterparty_id}/rolesList the roles a counterparty holds
POST/v1/counterparties/{counterparty_id}/rolesGive a counterparty a role
GET/v1/counterparties/{counterparty_id}/roles/{role_id}Get a counterparty's role
PATCH/v1/counterparties/{counterparty_id}/roles/{role_id}Change a counterparty's role
DELETE/v1/counterparties/{counterparty_id}/roles/{role_id}Take a role away from a counterparty

Guides: Keep track of vendors and customers

List the roles a counterparty holds

GET/v1/counterparties/{counterparty_id}/roles

client.partyRoles.list()

The roles a counterparty holds in these books, by role. A journal line may name a counterparty only once it holds one (decision 0086).

Parameters

Name	Type	Description
`counterparty_id`Path · Required	string	An id that starts with `party_`.
`limit`Query	integer	Page size, 1–200. Default 50
`cursor`Query	string or null	The `next_cursor` of the previous page.

Response

200PartyRolePage

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/counterparties/{counterparty_id}/roles" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Give a counterparty a role

POST/v1/counterparties/{counterparty_id}/roles· Idempotent

client.partyRoles.create()

Give a counterparty a role in these books: make them an investor, a lender, a vendor. Giving the customer or vendor role marks them one.

Refused with conflict when they hold it already (change that one), and with counterparty_merged for one merged into another.

Parameters

Name	Type	Description
`counterparty_id`Path · Required	string	An id that starts with `party_`.

Request body

NewPartyRole

Response

201PartyRoleOut

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/counterparties/{counterparty_id}/roles" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"role":"customer"}'

Get a counterparty's role

GET/v1/counterparties/{counterparty_id}/roles/{role_id}

client.partyRoles.get()

One role a counterparty holds.

Parameters

Name	Type	Description
`counterparty_id`Path · Required	string	An id that starts with `party_`.
`role_id`Path · Required	string	An id that starts with `party_role_`.

Response

200PartyRoleOut

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/counterparties/{counterparty_id}/roles/{role_id}" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Change a counterparty's role

PATCH/v1/counterparties/{counterparty_id}/roles/{role_id}· Idempotent

client.partyRoles.update()

Record whether a vendor is paid on a 1099, and on which form. Turning 1099 off clears the form.

Parameters

Name	Type	Description
`counterparty_id`Path · Required	string	An id that starts with `party_`.
`role_id`Path · Required	string	An id that starts with `party_role_`.

Request body

PartyRoleChanges

Response

200PartyRoleOut

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/counterparties/{counterparty_id}/roles/{role_id}" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

Take a role away from a counterparty

DELETE/v1/counterparties/{counterparty_id}/roles/{role_id}

client.partyRoles.delete()

Take a role away. Lines already posted keep naming them; a new line naming them needs them to hold some role. Removing the customer or vendor role unmarks them as one.

Parameters

Name	Type	Description
`counterparty_id`Path · Required	string	An id that starts with `party_`.
`role_id`Path · Required	string	An id that starts with `party_role_`.

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/counterparties/{counterparty_id}/roles/{role_id}" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Objects

The objects these operations take and return.

PartyRolePage

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

NewPartyRole

Name	Type	Description
`form_1099_category`	string or null	`nec` or `misc`, for a 1099-eligible vendor. One of `nec`, `misc`
`is_1099_eligible`	boolean	A vendor paid on a 1099. Default false
`role`Required	string	customer, vendor, employee, investor, lender or founder. One of `customer`, `vendor`, `employee`, `investor`, `lender`, `founder`

PartyRoleOut

Name	Type	Description
`counterparty_id`Required	string	The counterparty holding the role.
`created_at`Required	string (date-time)
`form_1099_category`Required	string or null	`nec` or `misc`: the form they are paid on. Null unless 1099-eligible. One of `nec`, `misc`
`id`Required	string	An id that starts with `party_role_`.
`is_1099_eligible`Required	boolean	A vendor paid on a 1099. Only a vendor role can be.
`role`Required	string	customer, vendor, employee, investor, lender or founder. One of `customer`, `vendor`, `employee`, `investor`, `lender`, `founder`
`updated_at`Required	string (date-time)

PartyRoleChanges

Only the fields sent change.

Name	Type	Description
`form_1099_category`	string or null	`nec` or `misc`; null clears it. One of `nec`, `misc`
`is_1099_eligible`	boolean	A vendor paid on a 1099.