People
People in the workspace, and the values their signatures use.
GET /v1/people
Everyone in the directory, filtered, a page at a time.
Scope people:read · listPeople
People in the workspace, a page at a time, ordered by name. Without status, everyone not removed.
The filters combine. q finds part of a name or an address; email and key find one person, by address or by the workspace's matching key; field with value finds people holding a value; missing finds people with no value for any of the fields it names. changed_since finds people whose changedAt is after a time: keep the latest changedAt you have seen, and ask for what changed since.
Pass a page's cursor to get the next; the last page has none.
Parameters
q query string
Part of a name or an address, matched anywhere, ignoring case.
At most 200 characters.
status query PersonStatus
Everyone not removed when absent. removed is the recycle bin.
field query string
A field name, with value. Both or neither.
Matches ^[a-z][a-z0-9_]{0,62}$.
value query string
What field must equal, ignoring case. For a multi-valued field, any one of its values.
At most 200 characters.
email query string
One address, whole, ignoring case: the person who has it, or nobody.
At most 320 characters.
key query string
The value of the workspace's matching key (FieldSetting.key), whole: the person who holds it, or nobody. Refused (400) while the workspace names no key.
At most 1000 characters.
changed_since query string (date-time)
People whose changedAt is after this: what a client polling for changes asks.
missing query string
Comma-separated field names, at most 60: people with no value, as signatures use it, for any one of them.
At most 4000 characters.
cursor query string
The previous page's cursor, for the next page.
limit query integer
People on a page.
1 to 200; default 50.
Responses
- 200 OK
One page.
application/json: PublicPeoplePage
- 400 Bad Request
A cursor that is not one of ours, field without value, key while the workspace names no matching key, or a missing field it does not offer.
application/problem+json: Problem
- 401 Unauthorized
A problem detail (RFC 9457); Errors lists those any call can meet.
application/problem+json: Problem
- 403 Forbidden
A problem detail (RFC 9457); Errors lists those any call can meet.
application/problem+json: Problem
- 429 Too Many Requests
too-many-requests: the client is over its limit, 600 requests a minute or 10 imports an hour. Retry-After says when to try again.
application/problem+json: ProblemRetry-After header: Seconds until the limit lets the next one through.
- default Any other error
A problem detail (RFC 9457); Errors lists those any call can meet.
application/problem+json: Problem
GET /v1/people/{id}
One person – their names, and each field's value and where it comes from.
Scope people:read · getPerson
One person: their names, and each field with any value set in Ascripto and what applies. A removed person is still found, with removedAt. The ETag header is their version, to send to patchPersonValues as If-Match.
Parameters
id path string (uuid) required
The person's id in this workspace.
Responses
- 200 OK
The person.
application/json: PublicPersonETag header: Their version, quoted ("42"): what patchPersonValues takes as If-Match.
- 401 Unauthorized
A problem detail (RFC 9457); Errors lists those any call can meet.
application/problem+json: Problem
- 403 Forbidden
A problem detail (RFC 9457); Errors lists those any call can meet.
application/problem+json: Problem
- 404 Not Found
A problem detail (RFC 9457); Errors lists those any call can meet.
application/problem+json: Problem
- 429 Too Many Requests
too-many-requests: the client is over its limit, 600 requests a minute or 10 imports an hour. Retry-After says when to try again.
application/problem+json: ProblemRetry-After header: Seconds until the limit lets the next one through.
- default Any other error
A problem detail (RFC 9457); Errors lists those any call can meet.
application/problem+json: Problem
PATCH /v1/people/{id}/values
Set some of one person's values and names; everything left out stays as it is.
Scope people:write · patchPersonValues
values names each field as templates bind it, with a list of values (one, for a field that holds one); [] sets a field to nothing on purpose; names sets the display, given and family names. On a field the directory fills, the value is an override that wins over the directory; on a field kept in Ascripto, it is the value. The address is never changed.
Each value is checked against its field's kind, and a refused one (value-refused) changes nothing. A value equal to what signatures already use changes nothing either. Send If-Match with getPerson's ETag to write only over the version you read. The change reaches the person's signature at once, and their History names your client. Requires Idempotency-Key.
Parameters
id path string (uuid) required
The person's id in this workspace.
If-Match header string
Their version as getPerson's ETag gave it ("42"): written only over that version. Absent writes over whatever is there.
At most 32 characters.
Request body
application/json: PersonValuesPatch
Responses
- 200 OK
The person, as they now are.
application/json: PublicPersonETag header: Their version now, quoted.
- 400 Bad Request
RFC 9457 problem detail. value-refused: a typed value is not its field's kind, and field and reason say which and why. Any other bad request is a plain problem.
application/problem+json: ValueRefusedProblem
- 401 Unauthorized
A problem detail (RFC 9457); Errors lists those any call can meet.
application/problem+json: Problem
- 403 Forbidden
A problem detail (RFC 9457); Errors lists those any call can meet.
application/problem+json: Problem
- 404 Not Found
No such person in this workspace, or they have been removed.
application/problem+json: Problem
- 412 Precondition Failed
version-mismatch: they changed after the version If-Match names; read them again.
application/problem+json: Problem
- 422 Unprocessable Content
unknown-field: not a field this workspace uses. one-value: several values for a field that holds one.
application/problem+json: Problem
- 429 Too Many Requests
too-many-requests: the client is over its limit, 600 requests a minute or 10 imports an hour. Retry-After says when to try again.
application/problem+json: ProblemRetry-After header: Seconds until the limit lets the next one through.
- default Any other error
A problem detail (RFC 9457); Errors lists those any call can meet.
application/problem+json: Problem
GET /v1/people/export
People as a spreadsheet – the list's filters, the chosen fields.
Scope people:read · exportPeople
People as a spreadsheet, to reconcile your records with Ascripto's: everyone listPeople would list with the same filters, in its order, one row each. The columns are id, the matching key's field when the workspace names one, email, then each of fields.
A cell holds the value signatures use; several values go one per line; a value set to nothing is -. XLSX is one sheet, every cell text. CSV is UTF-8 with a byte order mark (RFC 4180); a cell starting with =, +, - or @ is written after a ', which an import takes off again.
Parameters
format query SheetFormat required
fields query string required
Comma-separated template names, given_name, family_name and display_name among them; at most 60.
At most 4000 characters.
q query string
At most 200 characters.
status query PersonStatus
field query string
Matches ^[a-z][a-z0-9_]{0,62}$.
value query string
At most 200 characters.
Responses
- 200 OK
The file, named by Content-Disposition.
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet: filetext/csv: file
- 400 Bad Request
No fields, a field this workspace does not offer, or a filter listPeople refuses.
application/problem+json: Problem
- 401 Unauthorized
A problem detail (RFC 9457); Errors lists those any call can meet.
application/problem+json: Problem
- 403 Forbidden
A problem detail (RFC 9457); Errors lists those any call can meet.
application/problem+json: Problem
- 429 Too Many Requests
too-many-requests: the client is over its limit, 600 requests a minute or 10 imports an hour. Retry-After says when to try again.
application/problem+json: ProblemRetry-After header: Seconds until the limit lets the next one through.
- default Any other error
A problem detail (RFC 9457); Errors lists those any call can meet.
application/problem+json: Problem
POST /v1/people/imports
Read a spreadsheet and say what it would change – nothing is written yet.
Scope people:write · previewPeopleImport
Send a batch of values and see what it would change. The body is a spreadsheet as application/octet-stream (XLSX, its first sheet, or CSV; the first row names the columns), or JSON as application/json (PeopleImportJson); at most 10 MB and 100,000 rows.
Each row names one person: by the workspace's matching key, else id, else email. The address is never changed. A sheet's other columns are headed by a field's name or label; an empty cell leaves the value alone, and - sets it to nothing. A JSON row says what to set as patchPersonValues does: a field left out is untouched, [] is nothing on purpose. A value that is not its field's kind is a problem, and the rest of its row is left out.
Without apply, nothing is written: the answer is a preview with its problems, which applyPeopleImport applies within 24 hours. With apply=if-clean, a clean batch is applied at once and any other is held as waiting for an owner or an administrator (see Imports). A newer batch replaces one waiting. A client sends at most 10 imports an hour. Requires Idempotency-Key.
Parameters
name query string required
The file's name, or a JSON batch's, for History and the list.
1 to 200 characters.
apply query PeopleImportApply
if-clean: apply the batch at once if it is clean, else hold it as waiting. Absent, the batch waits as a preview until it is applied.
Request body
application/octet-stream: fileapplication/json: PeopleImportJson
Responses
- 200 OK
The preview; with apply=if-clean, the batch applied or waiting.
application/json: PeopleImport
- 400 Bad Request
sheet-unreadable: neither an XLSX nor a CSV we can read, or no id or email column. Over 100,000 rows. A JSON body that is not PeopleImportJson, a row naming not exactly one of key, id and email, or a key while the workspace names none.
application/problem+json: Problem
- 401 Unauthorized
A problem detail (RFC 9457); Errors lists those any call can meet.
application/problem+json: Problem
- 403 Forbidden
A problem detail (RFC 9457); Errors lists those any call can meet.
application/problem+json: Problem
- 413 Content Too Large
A problem detail (RFC 9457); Errors lists those any call can meet.
application/problem+json: Problem
- 429 Too Many Requests
too-many-requests: the client is over its limit, 600 requests a minute or 10 imports an hour. Retry-After says when to try again.
application/problem+json: ProblemRetry-After header: Seconds until the limit lets the next one through.
- default Any other error
A problem detail (RFC 9457); Errors lists those any call can meet.
application/problem+json: Problem
GET /v1/people/imports/{id}
One batch, as its preview said and, once applied or undone, as it went.
Scope people:read · getPeopleImport
One batch: what its preview said and, once applied or undone, what it did. Poll it to learn what became of a batch held as waiting.
Parameters
id path string (uuid) required
Responses
- 200 OK
The batch.
application/json: PeopleImport
- 401 Unauthorized
A problem detail (RFC 9457); Errors lists those any call can meet.
application/problem+json: Problem
- 403 Forbidden
A problem detail (RFC 9457); Errors lists those any call can meet.
application/problem+json: Problem
- 404 Not Found
A problem detail (RFC 9457); Errors lists those any call can meet.
application/problem+json: Problem
- 429 Too Many Requests
too-many-requests: the client is over its limit, 600 requests a minute or 10 imports an hour. Retry-After says when to try again.
application/problem+json: ProblemRetry-After header: Seconds until the limit lets the next one through.
- default Any other error
A problem detail (RFC 9457); Errors lists those any call can meet.
application/problem+json: Problem
GET /v1/people/imports/{id}/problems
Every problem the preview found, as a spreadsheet – the row, the column, why, the cell.
Scope people:read · getPeopleImportProblems
Every problem a batch's preview found, as a spreadsheet (XLSX or CSV): the row, the column, why, and what the cell held. The batch itself lists only the first 50.
Parameters
id path string (uuid) required
format query SheetFormat required
Responses
- 200 OK
The file.
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet: filetext/csv: file
- 401 Unauthorized
A problem detail (RFC 9457); Errors lists those any call can meet.
application/problem+json: Problem
- 403 Forbidden
A problem detail (RFC 9457); Errors lists those any call can meet.
application/problem+json: Problem
- 404 Not Found
A problem detail (RFC 9457); Errors lists those any call can meet.
application/problem+json: Problem
- 429 Too Many Requests
too-many-requests: the client is over its limit, 600 requests a minute or 10 imports an hour. Retry-After says when to try again.
application/problem+json: ProblemRetry-After header: Seconds until the limit lets the next one through.
- default Any other error
A problem detail (RFC 9457); Errors lists those any call can meet.
application/problem+json: Problem
POST /v1/people/imports/{id}/apply
Write what the preview said, and deliver it.
Scope people:write · applyPeopleImport
Apply a preview: each value still as the preview read it is written, and one changed meanwhile is left and counted in changedSince. The people it changed get their signatures at once, and each one's History names the batch. A batch held as waiting is applied by a person in Ascripto, never by a client (import-waiting). Requires Idempotency-Key.
Parameters
id path string (uuid) required
Responses
- 200 OK
The batch, applied.
application/json: PeopleImport
- 401 Unauthorized
A problem detail (RFC 9457); Errors lists those any call can meet.
application/problem+json: Problem
- 403 Forbidden
A problem detail (RFC 9457); Errors lists those any call can meet.
application/problem+json: Problem
- 404 Not Found
A problem detail (RFC 9457); Errors lists those any call can meet.
application/problem+json: Problem
- 409 Conflict
import-not-preview: applied, undone, or older than 24 hours. import-waiting: an API client applying a batch held as waiting, which a person applies.
application/problem+json: Problem
- 429 Too Many Requests
too-many-requests: the client is over its limit, 600 requests a minute or 10 imports an hour. Retry-After says when to try again.
application/problem+json: ProblemRetry-After header: Seconds until the limit lets the next one through.
- default Any other error
A problem detail (RFC 9457); Errors lists those any call can meet.
application/problem+json: Problem
POST /v1/people/imports/{id}/undo
Put back every value the batch changed, where it is still as the batch left it.
Scope people:write · undoPeopleImport
Put back every value an applied batch changed, where it is still as the batch left it; a value changed since is left and counted in changedSince. Once per batch. Requires Idempotency-Key.
Parameters
id path string (uuid) required
Responses
- 200 OK
The batch, undone.
application/json: PeopleImport
- 401 Unauthorized
A problem detail (RFC 9457); Errors lists those any call can meet.
application/problem+json: Problem
- 403 Forbidden
A problem detail (RFC 9457); Errors lists those any call can meet.
application/problem+json: Problem
- 404 Not Found
A problem detail (RFC 9457); Errors lists those any call can meet.
application/problem+json: Problem
- 409 Conflict
import-not-applied: a preview, or undone already.
application/problem+json: Problem
- 429 Too Many Requests
too-many-requests: the client is over its limit, 600 requests a minute or 10 imports an hour. Retry-After says when to try again.
application/problem+json: ProblemRetry-After header: Seconds until the limit lets the next one through.
- default Any other error
A problem detail (RFC 9457); Errors lists those any call can meet.
application/problem+json: Problem