Ascripto

Ascripto API

Version 0.122.0 · https://api.ascripto.com · openapi.json (OpenAPI 3.1.0)

The Ascripto API lets your own systems – an HR or IT integration, or a script – read the people in your workspace and keep the values their signatures use up to date: the fields your directory fills, and the fields kept in Ascripto. The same reference, as OpenAPI 3.1, is https://api.ascripto.com/openapi.json.

Base URL

Every call goes to https://api.ascripto.com, under /v1/. HTTPS only: never call http://, which sends your token in the clear before any redirect could stop it. Bodies are JSON; times are RFC 3339.

Making a client

An owner or an administrator of the workspace makes an API client in Ascripto, on Settings → API: its name and its scopes. A client acts for the whole workspace, and History names it beside every value it changes. It proves who it is by one of:

  • A secret, shown once, when it is made. A client may have two live secrets, so one can be replaced without stopping the integration.
  • A certificate: the public key of a key pair you keep (PEM or JWK; EC P-256, or RSA of 2048 bits or more), whose private key signs the client's assertion.

Revoking a client stops it taking tokens at once; a token it already holds lasts until it expires.

Taking a token

Take an access token from https://auth.ascripto.com/connect/token by the OAuth 2.0 client credentials grant. With a secret, send the client's id and secret by HTTP Basic authentication (client_secret_basic), or as client_id and client_secret in the form (client_secret_post):

curl https://auth.ascripto.com/connect/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d "scope=people:read people:write"

With a certificate (private_key_jwt), send an assertion instead of a secret:

curl https://auth.ascripto.com/connect/token \
  -d grant_type=client_credentials \
  -d client_id="$CLIENT_ID" \
  -d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
  -d client_assertion="$ASSERTION"

The assertion is a JWT signed with the certificate's private key, ES256 or RS256. Its header's typ must be client-authentication+jwt: an assertion typed JWT, as many libraries send by default, is refused. Its claims: iss and sub the client's id, aud https://auth.ascripto.com/, exp a minute or two ahead, iat, and a new jti each time.

Ask for the scopes you need in scope, or leave it out to be given every scope the client holds. The answer's access_token goes on every call, as Authorization: Bearer and the token. A token lasts five minutes (expires_in is 300): take a new one when it runs out, rather than keeping one.

Errors

Every error from the API is application/problem+json (RFC 9457): type, title, status, and often detail. type is https://ascripto.com/problems/ and a word; this reference names problems by the word. Those any call can meet:

  • 401 unauthenticated: no Authorization header. A token that has expired or is not valid is answered 401 with WWW-Authenticate: Bearer error="invalid_token": take a new one.
  • 403 https-required: the call went to http://, which answers no call, not even with a redirect. Call https://; the token it carried crossed the network unencrypted.
  • 403 permission: the token's scopes do not hold what the operation needs, which permission in the body names. 403 tenant-suspended or tenant-closed: the workspace can be read, not changed.
  • 429 too-many-requests: see Rate limits.
  • 400 idempotency-key-required, 409 idempotency-in-progress, 422 idempotency-key-reused: see Retrying a write.
  • 400 value-refused: a value is not its field's kind; field and reason say which and why.

The token endpoint answers as OAuth 2.0 does: invalid_client for an unknown or revoked client, a wrong secret or assertion, or a suspended or closed workspace; invalid_scope for a scope the client does not hold.

Retrying a write

Every POST and PATCH needs an Idempotency-Key header: 1 to 255 visible ASCII characters, new for each distinct request (a UUID will do). Sent again with the same key and the same request within 24 hours, a write is not done twice: the first answer comes back, marked Idempotent-Replayed: true. So a write whose answer was lost can safely be sent again. The same key with a different request is 422 idempotency-key-reused; while the first is still running, 409 idempotency-in-progress. A 5xx answer is not kept, so its retry runs afresh.

Changing one person

patchPersonValues sets some of one person's values and names, and leaves the rest as they are. To be sure of what you write over, read the person first: getPerson answers with an ETag, their version quoted ("42"). Send it back as If-Match; if they changed meanwhile, the patch is refused with 412 version-mismatch and nothing is written. Without If-Match, the patch writes over whatever is there.

Imports

To change many people at once, send a batch to previewPeopleImport: a spreadsheet (XLSX or CSV) or JSON (PeopleImportJson). Nothing is written yet: the answer, a PeopleImport, says what would change and lists the problems, and applyPeopleImport writes it within 24 hours. undoPeopleImport puts an applied batch back.

For an unattended feed, send apply=if-clean. A clean batch – no problems, and at most the larger of 200 people or a tenth of the workspace's active people changed – is applied at once; an owner or an administrator can change both numbers on Settings → API. Any other is held as waiting, with waiting.reasons saying why (problems, too-many), for an owner or an administrator to look at and apply in Ascripto within 24 hours; they are mailed when it is held. A client cannot apply a waiting batch (409 import-waiting); poll getPeopleImport to see what became of it. The first full load of a large workspace is held this way, by design.

The matching key

A workspace can name one field its matching key – an employee number, say – on Settings → Fields, by an owner or an administrator. Its values must be unique among active people. An import's rows then match people by the key first, then by id, then by address; listPeople finds one person by key, and listFields says which field it is. A key value two active people share makes the row ambiguous_key, never a guess; one nobody holds is key_not_found.

Following changes

listPeople with changed_since lists the people changed after a time, by their changedAt; with missing, the people with no value for a field. Poll them, within the rate limits.

Rate limits

Each client may send 600 requests a minute and 10 imports an hour (previewPeopleImport). Past either, the answer is 429 too-many-requests with Retry-After, the seconds to wait. Taking a token is not counted.

Scopes

A client is given one or more scopes when it is made, and asks for them at https://auth.ascripto.com/connect/token. Each operation needs one.

people:read

Read people, one or a page at a time, export them, and read imports and their problems.

people:write

Change people's values and names, one person at a time or by import; apply and undo imports.

fields:read

Read the workspace's fields.

Operations

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.

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.

401 Unauthorized

A problem detail (RFC 9457); Errors lists those any call can meet.

403 Forbidden

A problem detail (RFC 9457); Errors lists those any call can meet.

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: Problem
  • Retry-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.

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.

401 Unauthorized

A problem detail (RFC 9457); Errors lists those any call can meet.

403 Forbidden

A problem detail (RFC 9457); Errors lists those any call can meet.

404 Not Found

A problem detail (RFC 9457); Errors lists those any call can meet.

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: Problem
  • Retry-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.

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
Responses
200 OK

The person, as they now are.

  • application/json: PublicPerson
  • ETag 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.

401 Unauthorized

A problem detail (RFC 9457); Errors lists those any call can meet.

403 Forbidden

A problem detail (RFC 9457); Errors lists those any call can meet.

404 Not Found

No such person in this workspace, or they have been removed.

412 Precondition Failed

version-mismatch: they changed after the version If-Match names; read them again.

422 Unprocessable Content

unknown-field: not a field this workspace uses. one-value: several values for a field that holds one.

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: Problem
  • Retry-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.

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: file
  • text/csv: file
400 Bad Request

No fields, a field this workspace does not offer, or a filter listPeople refuses.

401 Unauthorized

A problem detail (RFC 9457); Errors lists those any call can meet.

403 Forbidden

A problem detail (RFC 9457); Errors lists those any call can meet.

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: Problem
  • Retry-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.

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
Responses
200 OK

The preview; with apply=if-clean, the batch applied or waiting.

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.

401 Unauthorized

A problem detail (RFC 9457); Errors lists those any call can meet.

403 Forbidden

A problem detail (RFC 9457); Errors lists those any call can meet.

413 Content Too Large

A problem detail (RFC 9457); Errors lists those any call can meet.

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: Problem
  • Retry-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.

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.

401 Unauthorized

A problem detail (RFC 9457); Errors lists those any call can meet.

403 Forbidden

A problem detail (RFC 9457); Errors lists those any call can meet.

404 Not Found

A problem detail (RFC 9457); Errors lists those any call can meet.

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: Problem
  • Retry-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.

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: file
  • text/csv: file
401 Unauthorized

A problem detail (RFC 9457); Errors lists those any call can meet.

403 Forbidden

A problem detail (RFC 9457); Errors lists those any call can meet.

404 Not Found

A problem detail (RFC 9457); Errors lists those any call can meet.

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: Problem
  • Retry-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.

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.

401 Unauthorized

A problem detail (RFC 9457); Errors lists those any call can meet.

403 Forbidden

A problem detail (RFC 9457); Errors lists those any call can meet.

404 Not Found

A problem detail (RFC 9457); Errors lists those any call can meet.

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.

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: Problem
  • Retry-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.

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.

401 Unauthorized

A problem detail (RFC 9457); Errors lists those any call can meet.

403 Forbidden

A problem detail (RFC 9457); Errors lists those any call can meet.

404 Not Found

A problem detail (RFC 9457); Errors lists those any call can meet.

409 Conflict

import-not-applied: a preview, or undone already.

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: Problem
  • Retry-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.

Fields

The fields signatures use, and where their values come from.

GET /v1/fields

Every field, switched on or off, with who holds a value and what binds it; and what the directory offers.

Scope fields:read · listFields

The workspace's fields: each one's name, as templates and this API name it; its label and kind; whether it holds one value or several; whether it is kept in Ascripto or filled from the directory; and whether it is the matching key (key). Also what the directory offers that no field takes yet.

Responses
200 OK

The fields.

401 Unauthorized

A problem detail (RFC 9457); Errors lists those any call can meet.

403 Forbidden

A problem detail (RFC 9457); Errors lists those any call can meet.

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: Problem
  • Retry-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.

Schemas

ApiClientRef

object

An API client, by its id and its name.

id string required
name string required

FieldSetting

object

One field: how templates and this API name it, its kind, where its values come from, and who uses it.

name string required
label string required
kind string required

One of text, phone, url, email, date, number, boolean.

multiValued boolean required
source string required

system is switched off, never removed; custom is this workspace's own.

One of system, custom.

enabled boolean required
people integer required

Active people holding a value.

usedBy array of FieldUse required

The signatures that bind it, published or in a draft.

rules integer required

How many rules test it.

filledFrom FieldSourceRef
suggestion FieldSourceRef
sourceChoosable boolean

Whether Filled from... is offered for it. Every field, while a Google or Microsoft directory is connected. Absent is false.

defaultSources array of string

The shipped keys that fill a system field when nothing is chosen, in order: the first that reads a value. Absent for a field with none.

kept boolean

Kept in Ascripto: the directory fills it no more, and its values are what administrators set. Absent is false.

fromDirectory integer

Active people whose value is the directory's, nobody having set one: who would lose it if the field were kept starting empty.

key boolean

The workspace's matching key: what an import's rows and listPeople's key find people by, before id and the address. One field at most. Absent is false.

FieldSettings

object

The workspace's fields, and what its directory offers that no field takes yet.

people integer required

Active people, for reading FieldSetting.people against.

fields array of FieldSetting required

Every field, switched on or off, in the order Settings → Fields shows them.

offered array of OfferedField required

Fields the directory supplied at its last read that this workspace has not defined, whose values are dropped until it does.

attributes array of ReadAttribute

The directory's own attributes at its latest full read, the customer's and not the provider's: what Filled from... offers.

sources array of ReadSelector

What the directory holds at its latest full read, by the source key that reads it: the rest of what Filled from... offers. Absent for a sample company.

sourcePeople integer

The people that read counted, what sources[].holders is out of.

FieldSourceRef

object

source string required
name string required
holders integer

People holding it at the directory's latest full read; on filledFrom, 0 also when that read found nobody holding it. Absent when unknown.

FieldUse

object

id string (uuid) required
name string required

OfferedField

object

name string required
seenAt string (date-time) required
source string

The attribute it comes from, when one does.

kind string

The kind its values suggest, for defining it.

One of text, phone, url, email, date, number, boolean.

multiValued boolean

Whether somebody holds several values.

holders integer

People with a value.

PeopleImport

object

A batch of values, a spreadsheet's or JSON's: what it would change, then what it did.

id string (uuid) required
file string required
status string required

preview: read, nothing written yet. applied. undone. waiting: sent with apply=if-clean and not clean, so held for an owner or an administrator to apply; waiting says why. expired: a preview or a waiting batch older than 24 hours, which can no longer be applied.

One of preview, applied, undone, expired, waiting.

waiting PeopleImportWaiting
at string (date-time) required

When it was read.

by string required

Who sent it: a person's id, or the API client's id when client is present.

client ApiClientRef

The API client that sent it.

appliedAt string (date-time)
appliedBy string
undoneAt string (date-time)
undoneBy string
rows integer required

Rows below the headings.

people integer required

People whose values it changes (changed, once applied).

values integer required

Values it changes, one per person and field.

overrides integer required

Of values, those on a field the directory still fills – an override each.

changedSince integer

Applied or undone, the values left because they had moved meanwhile.

columns array of string required

The columns it read, by field, in the sheet's order; id and email included.

problems object required
total integer required
first array of PeopleImportProblem required

At most 50 items.

PeopleImportApply

string

if-clean: apply at once a batch with no problems that changes at most PeopleImportWaiting.limit people; hold any other as waiting.

One of if-clean.

PeopleImportJson

object

An import as an API client sends it: the rows of a sheet, each a person and what to set.

rows array of PeopleImportJsonRow required

1 to 100000 items.

PeopleImportJsonRow

object

Exactly one of key (the value of the workspace's matching key), id and email, which say who and are never written; then names and values, as PersonValuesPatch takes them.

key string

At most 1000 characters.

id string (uuid)
email string

At most 320 characters.

names PersonNamesPatch
values object of array of string, by name

By field name, as a template binds it, each a list: one element for a field that holds one. A field left out is untouched; [] is nothing on purpose. Never email.

At most 200 names; each at most 100 items; each at most 1000 characters.

PeopleImportProblem

object

row integer required

The sheet's row number, the headings being 1; a JSON batch's row, its place in rows from 1.

At least 1.

column string

The heading as written.

code PeopleImportProblemCode required
reason ValueRefusal
cell string

What the cell held, at most 200 characters.

sameAs integer

For same_person, the row that matched them first.

PeopleImportProblemCode

string

no_person: neither id nor email matches anybody here (the recycle bin is nobody). same_person: an earlier row matched the same person, and this one is left out. one_value: several lines in a field that holds one. refused: not a value of the field's kind, reason says why. too_many: over 100 values. too_long: a value over 1000 characters. not_a_field: a heading that names no field this workspace offers, nor id, email or a name; its column is left out (row 1). ambiguous_key: more than one active person holds the row's key value, so it is left out rather than guessed; key_not_found: nobody here holds it.

One of no_person, same_person, one_value, refused, too_many, too_long, not_a_field, ambiguous_key, key_not_found.

PeopleImportWaiting

object

Why a batch sent with apply=if-clean was held.

reasons array of PeopleImportWaitingReason required

At least 1 items; no item twice.

limit integer required

The most people a clean batch may change unattended: the workspace's setting, by default the larger of 200 and a tenth of its active people.

changed integer required

The people this one would change.

PeopleImportWaitingReason

string

problems: the preview found some. too-many: it would change more than limit people.

One of problems, too-many.

PersonNamesPatch

object

A person's names, each set as an override is: one left out is untouched, "" is nothing on purpose.

displayName string

At most 1000 characters.

givenName string

At most 1000 characters.

familyName string

At most 1000 characters.

PersonStatus

string

active; suspended in the directory; or removed, the recycle bin: gone from the directory, kept for the connection's retention, and back as they were if the directory shows them again.

One of active, suspended, removed.

PersonValuesPatch

object

At least one of values and names; never the address.

At least 1 names.

values object of array of string, by name

By field name, as a template binds it, each a list: one element for a field that holds one. A field left out is untouched; [] is nothing on purpose. Never email.

At most 200 names; each at most 100 items; each at most 1000 characters.

names PersonNamesPatch

Problem

object

An RFC 9457 problem detail, which every error is. type names the problem: https://ascripto.com/problems/ and a word, such as permission.

type string (uri) required

A URI identifying the problem type.

Default "about:blank".

Example: "https://ascripto.com/problems/tenant-suspended"

title string required

Short, human-readable summary. Stable for a given type.

Example: "Tenant suspended"

status integer (int32) required

The HTTP status code, repeated in the body.

100 to 599.

Example: 403

detail string

Human-readable explanation specific to this occurrence. Never carries a secret, a token, or an echo of a submitted credential.

instance string (uri-reference)

A URI identifying this specific occurrence.

traceId string

Correlates this response with the server-side trace.

Example: "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01"

PublicPeoplePage

object

One page of people.

people array of PublicPersonRow required
cursor string

The next page's; pass it as cursor. Absent on the last.

PublicPerson

object

One person: their names, each field with any value set in Ascripto and what applies, and their version.

id string (uuid) required
email string required
status PersonStatus required
displayName string required

As signatures use it: the value set in Ascripto, else the directory's. Empty when there is none.

givenName string required

As displayName, for the given name.

familyName string required

As displayName, for the family name.

removedAt string (date-time)

When they left the directory; only while status is removed.

fields array of PublicPersonField required

The three names (display_name, given_name, family_name), then every enabled field of the workspace in its order, including those this person has no value for.

version integer (int64) required

Moves on every real change to them: what getPerson's ETag quotes and patchPersonValues' If-Match compares.

changedAt string (date-time) required

When version last moved.

PublicPersonField

object

One of a person's fields: any value set in Ascripto, and what applies.

name string required

The field's name, as templates bind it and patchPersonValues names it.

value array of string required

What applies: the value set in Ascripto when there is one, else the directory's. Empty when neither has one.

override array of string

The value set in Ascripto, when there is one: on a field the directory fills, an override that wins over it. Empty is set to nothing on purpose, which is not the same as none.

kept boolean

The field is kept in Ascripto: the directory never fills it, and override is simply its value. Absent is false.

PublicPersonRow

object

One person, as listPeople lists them.

id string (uuid) required
email string required
name string required

The display name as signatures use it. Empty when there is none.

status PersonStatus required
removedAt string (date-time)

When they left the directory; only while status is removed.

version integer (int64) required

Moves on every real change to them, as getPerson's version.

changedAt string (date-time) required

When version last moved; what changed_since compares.

ReadAttribute

object

source string required

Where the provider keeps it; for one of its own, the field it fills.

name string required
field string

The field name it arrives under. Absent when its name makes none.

status ReadAttributeStatus required
holders integer required
maxValues integer required
kind string required

The most particular kind every value fits.

One of text, phone, url, email, date, number, boolean.

suggestedFor string

A field nobody filled that this is likely meant for.

ReadAttributeStatus

string

How Ascripto reads a directory attribute. builtin: one of the provider's own, filled as Ascripto maps it. matched: a field has its name. mapped: a field names it as its source. unmapped: nothing takes it. unnamable: its name makes no field name. collides: another attribute arrives under the same field name. ignored: the workspace said so.

One of builtin, matched, mapped, unmapped, unnamable, collides, ignored.

ReadSelector

object

A source key a field can be filled from, taken apart, with how many people hold a value there: an array and how its elements are picked (phones[work]), an element's value (organizations[work].title), or a single value (jobTitle).

key string required

The whole source key.

array string

The array it picks from (phones, customSchemas.hr.languages). Absent for a scalar.

selector ReadSelectorKind
word string

The type (work) or custom type (Main office) it picks by. Absent for the other selectors.

leaf string

The element's value it reads (title, address.locality). Absent when the element has one value.

holders integer required

People with at least one element it picks from.

maxValues integer required

The most such elements one person has.

ReadSelectorKind

string

How a source key picks from an array: every takes every element ([*]); auto the element marked primary, else (Google) the one typed work, else the first; primary only the one marked primary; type the elements of one type ([work]); custom the element of a type the customer named.

One of every, auto, primary, type, custom.

SheetFormat

string

A People spreadsheet's file format. json: an import sent as application/json, PeopleImportJson; the export and the problems file are XLSX or CSV, and refuse it.

One of xlsx, csv, json.

ValueRefusal

string

Why a value is not its field's kind; text and addresses take anything. not_phone: digits, + ( ) . / - and spaces, then an extension word and its digits if any, at least five digits. not_email: one bare address with a dotted host. not_web: http or https, or no scheme, with a dotted host. not_date: yyyy-MM-dd. not_number: written with a dot. not_yes_no: true, false, yes or no.

One of not_phone, not_email, not_web, not_date, not_number, not_yes_no.

ValueRefusedProblem

Problem, and the properties below

A Problem; when its type is https://ascripto.com/problems/value-refused, a value is not its field's kind, and field and reason say which (the first such) and why. Any other problem carries neither.

field string

The field's name, as the request gave it.

reason ValueRefusal