{
  "openapi": "3.1.0",
  "info": {
    "title": "Ascripto API",
    "version": "0.122.0",
    "description": "The Ascripto API lets your own systems -- an HR or IT integration, or a script -- read the people in your\nworkspace and keep the values their signatures use up to date: the fields your directory fills, and the fields\nkept in Ascripto. The same reference, as OpenAPI 3.1, is `https://api.ascripto.com/openapi.json`.\n\n## Base URL\n\nEvery call goes to `https://api.ascripto.com`, under `/v1/`. **HTTPS only**: never call `http://`, which\nsends your token in the clear before any redirect could stop it. Bodies are JSON; times are RFC 3339.\n\n## Making a client\n\nAn owner or an administrator of the workspace makes an API client in Ascripto, on **Settings -> API**: its\nname and its scopes. A client acts for the whole workspace, and History names it beside every value it\nchanges. It proves who it is by one of:\n\n- **A secret**, shown once, when it is made. A client may have two live secrets, so one can be replaced\n  without stopping the integration.\n- **A certificate**: the public key of a key pair you keep (PEM or JWK; EC P-256, or RSA of 2048 bits or\n  more), whose private key signs the client's assertion.\n\nRevoking a client stops it taking tokens at once; a token it already holds lasts until it expires.\n\n## Taking a token\n\nTake an access token from `https://auth.ascripto.com/connect/token` by the OAuth 2.0 client credentials\ngrant. With a secret, send the client's id and secret by HTTP Basic authentication (`client_secret_basic`), or\nas `client_id` and `client_secret` in the form (`client_secret_post`):\n\n```sh\ncurl https://auth.ascripto.com/connect/token \\\n  -u \"$CLIENT_ID:$CLIENT_SECRET\" \\\n  -d grant_type=client_credentials \\\n  -d \"scope=people:read people:write\"\n```\n\nWith a certificate (`private_key_jwt`), send an assertion instead of a secret:\n\n```sh\ncurl https://auth.ascripto.com/connect/token \\\n  -d grant_type=client_credentials \\\n  -d client_id=\"$CLIENT_ID\" \\\n  -d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \\\n  -d client_assertion=\"$ASSERTION\"\n```\n\nThe assertion is a JWT signed with the certificate's private key, ES256 or RS256. Its header's `typ` **must be\n`client-authentication+jwt`**: an assertion typed `JWT`, as many libraries send by default, is refused. Its\nclaims: `iss` and `sub` the client's id, `aud` `https://auth.ascripto.com/`, `exp` a minute or two ahead,\n`iat`, and a new `jti` each time.\n\nAsk for the scopes you need in `scope`, or leave it out to be given every scope the client holds. The answer's\n`access_token` goes on every call, as `Authorization: Bearer` and the token. **A token lasts five minutes**\n(`expires_in` is 300): take a new one when it runs out, rather than keeping one.\n\n## Errors\n\nEvery error from the API is `application/problem+json` (RFC 9457): `type`, `title`, `status`, and often\n`detail`. `type` is `https://ascripto.com/problems/` and a word; this reference names problems by the word.\nThose any call can meet:\n\n- `401` `unauthenticated`: no `Authorization` header. A token that has expired or is not valid is answered\n  `401` with `WWW-Authenticate: Bearer error=\"invalid_token\"`: take a new one.\n- `403` `https-required`: the call went to `http://`, which answers no call, not even with a redirect. Call\n  `https://`; the token it carried crossed the network unencrypted.\n- `403` `permission`: the token's scopes do not hold what the operation needs, which `permission` in the\n  body names. `403` `tenant-suspended` or `tenant-closed`: the workspace can be read, not changed.\n- `429` `too-many-requests`: see *Rate limits*.\n- `400` `idempotency-key-required`, `409` `idempotency-in-progress`, `422` `idempotency-key-reused`: see\n  *Retrying a write*.\n- `400` `value-refused`: a value is not its field's kind; `field` and `reason` say which and why.\n\nThe token endpoint answers as OAuth 2.0 does: `invalid_client` for an unknown or revoked client, a wrong\nsecret or assertion, or a suspended or closed workspace; `invalid_scope` for a scope the client does not hold.\n\n## Retrying a write\n\nEvery `POST` and `PATCH` needs an `Idempotency-Key` header: 1 to 255 visible ASCII characters, new for each\ndistinct request (a UUID will do). Sent again with the same key and the same request within 24 hours, a write\nis not done twice: the first answer comes back, marked `Idempotent-Replayed: true`. So a write whose answer was\nlost can safely be sent again. The same key with a different request is `422` `idempotency-key-reused`; while\nthe first is still running, `409` `idempotency-in-progress`. A `5xx` answer is not kept, so its retry runs\nafresh.\n\n## Changing one person\n\n`patchPersonValues` sets some of one person's values and names, and leaves the rest as they are. To be sure of\nwhat you write over, read the person first: `getPerson` answers with an `ETag`, their `version` quoted\n(`\"42\"`). Send it back as `If-Match`; if they changed meanwhile, the patch is refused with `412`\n`version-mismatch` and nothing is written. Without `If-Match`, the patch writes over whatever is there.\n\n## Imports\n\nTo change many people at once, send a batch to `previewPeopleImport`: a spreadsheet (XLSX or CSV) or JSON\n(`PeopleImportJson`). Nothing is written yet: the answer, a `PeopleImport`, says what would change and lists\nthe problems, and `applyPeopleImport` writes it within 24 hours. `undoPeopleImport` puts an applied batch\nback.\n\nFor an unattended feed, send `apply=if-clean`. A clean batch -- no problems, and at most the larger of 200\npeople or a tenth of the workspace's active people changed -- is applied at once; an owner or an administrator\ncan change both numbers on **Settings -> API**. Any other is held as `waiting`, with `waiting.reasons` saying\nwhy (`problems`, `too-many`), for an owner or an administrator to look at and apply in Ascripto within 24\nhours; they are mailed when it is held. A client cannot apply a waiting batch (`409` `import-waiting`); poll\n`getPeopleImport` to see what became of it. The first full load of a large workspace is held this way, by\ndesign.\n\n## The matching key\n\nA workspace can name one field its matching key -- an employee number, say -- on **Settings -> Fields**, by an\nowner or an administrator. Its values must be unique among active people. An import's rows then match people\nby the key first, then by `id`, then by address; `listPeople` finds one person by `key`, and `listFields` says\nwhich field it is. A key value two active people share makes the row `ambiguous_key`, never a guess; one\nnobody holds is `key_not_found`.\n\n## Following changes\n\n`listPeople` with `changed_since` lists the people changed after a time, by their `changedAt`; with `missing`,\nthe people with no value for a field. Poll them, within the rate limits.\n\n## Rate limits\n\nEach client may send **600 requests a minute** and **10 imports an hour** (`previewPeopleImport`). Past\neither, the answer is `429` `too-many-requests` with `Retry-After`, the seconds to wait. Taking a token is not\ncounted.\n",
    "license": {
      "name": "Proprietary",
      "url": "https://ascripto.com/"
    }
  },
  "servers": [
    {
      "url": "https://api.ascripto.com"
    }
  ],
  "tags": [
    {
      "name": "people",
      "description": "People in the workspace, and the values their signatures use."
    },
    {
      "name": "fields",
      "description": "The fields signatures use, and where their values come from."
    }
  ],
  "paths": {
    "/v1/people": {
      "get": {
        "tags": [
          "people"
        ],
        "operationId": "listPeople",
        "summary": "Everyone in the directory, filtered, a page at a time.",
        "description": "People in the workspace, a page at a time, ordered by name. Without `status`, everyone not removed.\n\nThe filters combine. `q` finds part of a name or an address; `email` and `key` find one person, by address\nor by the workspace's matching key; `field` with `value` finds people holding a value; `missing` finds people\nwith no value for any of the fields it names. `changed_since` finds people whose `changedAt` is after a time:\nkeep the latest `changedAt` you have seen, and ask for what changed since.\n\nPass a page's `cursor` to get the next; the last page has none.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Part of a name or an address, matched anywhere, ignoring case.",
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Everyone not removed when absent. `removed` is the recycle bin.",
            "schema": {
              "$ref": "#/components/schemas/PersonStatus"
            }
          },
          {
            "name": "field",
            "in": "query",
            "required": false,
            "description": "A field name, with `value`. Both or neither.",
            "schema": {
              "type": "string",
              "pattern": "^[a-z][a-z0-9_]{0,62}$"
            }
          },
          {
            "name": "value",
            "in": "query",
            "required": false,
            "description": "What `field` must equal, ignoring case. For a multi-valued field, any one of its values.",
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          },
          {
            "name": "email",
            "in": "query",
            "required": false,
            "description": "One address, whole, ignoring case: the person who has it, or nobody.",
            "schema": {
              "type": "string",
              "maxLength": 320
            }
          },
          {
            "name": "key",
            "in": "query",
            "required": false,
            "description": "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.",
            "schema": {
              "type": "string",
              "maxLength": 1000
            }
          },
          {
            "name": "changed_since",
            "in": "query",
            "required": false,
            "description": "People whose `changedAt` is after this: what a client polling for changes asks.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "missing",
            "in": "query",
            "required": false,
            "description": "Comma-separated field names, at most 60: people with no value, as signatures use it, for any one of them.",
            "schema": {
              "type": "string",
              "maxLength": 4000
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "The previous page's `cursor`, for the next page."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            },
            "description": "People on a page."
          }
        ],
        "security": [
          {
            "oauth2": [
              "people:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "One page.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicPeoplePage"
                }
              }
            }
          },
          "400": {
            "description": "A `cursor` that is not one of ours, `field` without `value`, `key` while the workspace names no matching\nkey, or a `missing` field it does not offer.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Problem"
          },
          "403": {
            "$ref": "#/components/responses/Problem"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/people/{id}": {
      "get": {
        "tags": [
          "people"
        ],
        "operationId": "getPerson",
        "summary": "One person -- their names, and each field's value and where it comes from.",
        "description": "One person: their names, and each field with any value set in Ascripto and what applies. A removed person is\nstill found, with `removedAt`. The `ETag` header is their `version`, to send to `patchPersonValues` as\n`If-Match`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/PersonId"
          }
        ],
        "security": [
          {
            "oauth2": [
              "people:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The person.",
            "headers": {
              "ETag": {
                "description": "Their `version`, quoted (`\"42\"`): what `patchPersonValues` takes as `If-Match`.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicPerson"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Problem"
          },
          "403": {
            "$ref": "#/components/responses/Problem"
          },
          "404": {
            "$ref": "#/components/responses/Problem"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/people/{id}/values": {
      "patch": {
        "tags": [
          "people"
        ],
        "operationId": "patchPersonValues",
        "summary": "Set some of one person's values and names; everything left out stays as it is.",
        "description": "`values` names each field as templates bind it, with a list of values (one, for a field that holds one);\n`[]` sets a field to nothing on purpose; `names` sets the display, given and family names. On a field the\ndirectory fills, the value is an override that wins over the directory; on a field kept in Ascripto, it is\nthe value. The address is never changed.\n\nEach value is checked against its field's kind, and a refused one (`value-refused`) changes nothing. A value\nequal to what signatures already use changes nothing either. Send `If-Match` with `getPerson`'s `ETag` to\nwrite only over the version you read. The change reaches the person's signature at once, and their History\nnames your client. Requires `Idempotency-Key`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/PersonId"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "Their `version` as `getPerson`'s `ETag` gave it (`\"42\"`): written only over that version. Absent writes over whatever is there.",
            "schema": {
              "type": "string",
              "maxLength": 32
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PersonValuesPatch"
              }
            }
          }
        },
        "security": [
          {
            "oauth2": [
              "people:write"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The person, as they now are.",
            "headers": {
              "ETag": {
                "description": "Their `version` now, quoted.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicPerson"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValueRefused"
          },
          "401": {
            "$ref": "#/components/responses/Problem"
          },
          "403": {
            "$ref": "#/components/responses/Problem"
          },
          "404": {
            "description": "No such person in this workspace, or they have been removed.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "412": {
            "description": "`version-mismatch`: they changed after the version `If-Match` names; read them again.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "`unknown-field`: not a field this workspace uses. `one-value`: several values for a field that holds one.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/people/export": {
      "get": {
        "tags": [
          "people"
        ],
        "operationId": "exportPeople",
        "summary": "People as a spreadsheet -- the list's filters, the chosen fields.",
        "description": "People as a spreadsheet, to reconcile your records with Ascripto's: everyone `listPeople` would list with\nthe same filters, in its order, one row each. The columns are `id`, the matching key's field when the\nworkspace names one, `email`, then each of `fields`.\n\nA cell holds the value signatures use; several values go one per line; a value set to nothing is `-`. XLSX\nis one sheet, every cell text. CSV is UTF-8 with a byte order mark (RFC 4180); a cell starting with `=`,\n`+`, `-` or `@` is written after a `'`, which an import takes off again.",
        "parameters": [
          {
            "name": "format",
            "in": "query",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/SheetFormat"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": true,
            "description": "Comma-separated template names, `given_name`, `family_name` and `display_name` among them; at most 60.",
            "schema": {
              "type": "string",
              "maxLength": 4000
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/PersonStatus"
            }
          },
          {
            "name": "field",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[a-z][a-z0-9_]{0,62}$"
            }
          },
          {
            "name": "value",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          }
        ],
        "security": [
          {
            "oauth2": [
              "people:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The file, named by `Content-Disposition`.",
            "content": {
              "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "No fields, a field this workspace does not offer, or a filter `listPeople` refuses.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Problem"
          },
          "403": {
            "$ref": "#/components/responses/Problem"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/people/imports": {
      "post": {
        "tags": [
          "people"
        ],
        "operationId": "previewPeopleImport",
        "summary": "Read a spreadsheet and say what it would change -- nothing is written yet.",
        "description": "Send a batch of values and see what it would change. The body is a spreadsheet as `application/octet-stream`\n(XLSX, its first sheet, or CSV; the first row names the columns), or JSON as `application/json`\n(`PeopleImportJson`); at most 10 MB and 100,000 rows.\n\nEach row names one person: by the workspace's matching key, else `id`, else `email`. The address is never\nchanged. A sheet's other columns are headed by a field's name or label; an empty cell leaves the value alone,\nand `-` sets it to nothing. A JSON row says what to set as `patchPersonValues` does: a field left out is\nuntouched, `[]` is nothing on purpose. A value that is not its field's kind is a problem, and the rest of its\nrow is left out.\n\nWithout `apply`, nothing is written: the answer is a preview with its problems, which\n`applyPeopleImport` applies within 24 hours. With `apply=if-clean`, a clean batch is applied at once and any\nother is held as `waiting` for an owner or an administrator (see *Imports*). A newer batch replaces one\nwaiting. A client sends at most 10 imports an hour. Requires `Idempotency-Key`.",
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "required": true,
            "description": "The file's name, or a JSON batch's, for History and the list.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            }
          },
          {
            "name": "apply",
            "in": "query",
            "required": false,
            "description": "`if-clean`: apply the batch at once if it is clean, else hold it as `waiting`. Absent, the batch waits as\na preview until it is applied.",
            "schema": {
              "$ref": "#/components/schemas/PeopleImportApply"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/octet-stream": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PeopleImportJson"
              }
            }
          }
        },
        "security": [
          {
            "oauth2": [
              "people:write"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The preview; with `apply=if-clean`, the batch applied or `waiting`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PeopleImport"
                }
              }
            }
          },
          "400": {
            "description": "`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.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Problem"
          },
          "403": {
            "$ref": "#/components/responses/Problem"
          },
          "413": {
            "$ref": "#/components/responses/Problem"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/people/imports/{id}": {
      "get": {
        "tags": [
          "people"
        ],
        "operationId": "getPeopleImport",
        "summary": "One batch, as its preview said and, once applied or undone, as it went.",
        "description": "One batch: what its preview said and, once applied or undone, what it did. Poll it to learn what became of a\nbatch held as `waiting`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "oauth2": [
              "people:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The batch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PeopleImport"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Problem"
          },
          "403": {
            "$ref": "#/components/responses/Problem"
          },
          "404": {
            "$ref": "#/components/responses/Problem"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/people/imports/{id}/problems": {
      "get": {
        "tags": [
          "people"
        ],
        "operationId": "getPeopleImportProblems",
        "summary": "Every problem the preview found, as a spreadsheet -- the row, the column, why, the cell.",
        "description": "Every problem a batch's preview found, as a spreadsheet (XLSX or CSV): the row, the column, why, and what the\ncell held. The batch itself lists only the first 50.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/SheetFormat"
            }
          }
        ],
        "security": [
          {
            "oauth2": [
              "people:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The file.",
            "content": {
              "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Problem"
          },
          "403": {
            "$ref": "#/components/responses/Problem"
          },
          "404": {
            "$ref": "#/components/responses/Problem"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/people/imports/{id}/apply": {
      "post": {
        "tags": [
          "people"
        ],
        "operationId": "applyPeopleImport",
        "summary": "Write what the preview said, and deliver it.",
        "description": "Apply a preview: each value still as the preview read it is written, and one changed meanwhile is left and\ncounted in `changedSince`. The people it changed get their signatures at once, and each one's History names\nthe batch. A batch held as `waiting` is applied by a person in Ascripto, never by a client\n(`import-waiting`). Requires `Idempotency-Key`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "oauth2": [
              "people:write"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The batch, applied.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PeopleImport"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Problem"
          },
          "403": {
            "$ref": "#/components/responses/Problem"
          },
          "404": {
            "$ref": "#/components/responses/Problem"
          },
          "409": {
            "description": "`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.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/people/imports/{id}/undo": {
      "post": {
        "tags": [
          "people"
        ],
        "operationId": "undoPeopleImport",
        "summary": "Put back every value the batch changed, where it is still as the batch left it.",
        "description": "Put back every value an applied batch changed, where it is still as the batch left it; a value changed since is\nleft and counted in `changedSince`. Once per batch. Requires `Idempotency-Key`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "oauth2": [
              "people:write"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The batch, undone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PeopleImport"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Problem"
          },
          "403": {
            "$ref": "#/components/responses/Problem"
          },
          "404": {
            "$ref": "#/components/responses/Problem"
          },
          "409": {
            "description": "`import-not-applied`: a preview, or undone already.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/fields": {
      "get": {
        "tags": [
          "fields"
        ],
        "operationId": "listFields",
        "summary": "Every field, switched on or off, with who holds a value and what binds it; and what the directory offers.",
        "description": "The workspace's fields: each one's name, as templates and this API name it; its label and kind; whether it\nholds one value or several; whether it is kept in Ascripto or filled from the directory; and whether it is the\nmatching key (`key`). Also what the directory offers that no field takes yet.",
        "security": [
          {
            "oauth2": [
              "fields:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The fields.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FieldSettings"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Problem"
          },
          "403": {
            "$ref": "#/components/responses/Problem"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "description": "OAuth 2.0 client credentials: a client secret or a signed assertion (`private_key_jwt`).",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://auth.ascripto.com/connect/token",
            "scopes": {
              "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."
            }
          }
        }
      }
    },
    "parameters": {
      "PersonId": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "The person's id in this workspace.",
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      }
    },
    "responses": {
      "Problem": {
        "description": "A problem detail (RFC 9457); *Errors* lists those any call can meet.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "`too-many-requests`: the client is over its limit, 600 requests a minute or 10 imports an hour.\n`Retry-After` says when to try again.",
        "headers": {
          "Retry-After": {
            "description": "Seconds until the limit lets the next one through.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "ValueRefused": {
        "description": "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.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ValueRefusedProblem"
            }
          }
        }
      }
    },
    "schemas": {
      "ApiClientRef": {
        "type": "object",
        "title": "ApiClientRef",
        "description": "An API client, by its id and its name.",
        "required": [
          "id",
          "name"
        ],
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          }
        }
      },
      "ReadAttribute": {
        "type": "object",
        "title": "ReadAttribute",
        "required": [
          "source",
          "name",
          "status",
          "holders",
          "maxValues",
          "kind"
        ],
        "additionalProperties": false,
        "properties": {
          "source": {
            "type": "string",
            "description": "Where the provider keeps it; for one of its own, the field it fills."
          },
          "name": {
            "type": "string"
          },
          "field": {
            "type": "string",
            "description": "The field name it arrives under. Absent when its name makes none."
          },
          "status": {
            "$ref": "#/components/schemas/ReadAttributeStatus"
          },
          "holders": {
            "type": "integer",
            "minimum": 0
          },
          "maxValues": {
            "type": "integer",
            "minimum": 0
          },
          "kind": {
            "type": "string",
            "enum": [
              "text",
              "phone",
              "url",
              "email",
              "date",
              "number",
              "boolean"
            ],
            "description": "The most particular kind every value fits."
          },
          "suggestedFor": {
            "type": "string",
            "description": "A field nobody filled that this is likely meant for."
          }
        }
      },
      "ReadSelector": {
        "type": "object",
        "title": "ReadSelector",
        "description": "A source key a field can be filled from, taken apart, with how many people hold a value there: an array\nand how its elements are picked (`phones[work]`), an element's value (`organizations[work].title`), or a\nsingle value (`jobTitle`).",
        "required": [
          "key",
          "holders",
          "maxValues"
        ],
        "additionalProperties": false,
        "properties": {
          "key": {
            "type": "string",
            "description": "The whole source key."
          },
          "array": {
            "type": "string",
            "description": "The array it picks from (`phones`, `customSchemas.hr.languages`). Absent for a scalar."
          },
          "selector": {
            "$ref": "#/components/schemas/ReadSelectorKind"
          },
          "word": {
            "type": "string",
            "description": "The type (`work`) or custom type (`Main office`) it picks by. Absent for the other selectors."
          },
          "leaf": {
            "type": "string",
            "description": "The element's value it reads (`title`, `address.locality`). Absent when the element has one value."
          },
          "holders": {
            "type": "integer",
            "minimum": 0,
            "description": "People with at least one element it picks from."
          },
          "maxValues": {
            "type": "integer",
            "minimum": 0,
            "description": "The most such elements one person has."
          }
        }
      },
      "ReadSelectorKind": {
        "type": "string",
        "title": "ReadSelectorKind",
        "enum": [
          "every",
          "auto",
          "primary",
          "type",
          "custom"
        ],
        "description": "How a source key picks from an array: `every` takes every element (`[*]`); `auto` the element marked\nprimary, else (Google) the one typed `work`, else the first; `primary` only the one marked primary; `type`\nthe elements of one type (`[work]`); `custom` the element of a type the customer named."
      },
      "FieldSourceRef": {
        "type": "object",
        "title": "FieldSourceRef",
        "required": [
          "source",
          "name"
        ],
        "additionalProperties": false,
        "properties": {
          "source": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "holders": {
            "type": "integer",
            "minimum": 0,
            "description": "People holding it at the directory's latest full read; on `filledFrom`, `0` also when that read found\nnobody holding it. Absent when unknown."
          }
        }
      },
      "ReadAttributeStatus": {
        "type": "string",
        "title": "ReadAttributeStatus",
        "enum": [
          "builtin",
          "matched",
          "mapped",
          "unmapped",
          "unnamable",
          "collides",
          "ignored"
        ],
        "description": "How Ascripto reads a directory attribute. `builtin`: one of the provider's own, filled as Ascripto maps\nit. `matched`: a field has its name. `mapped`: a field names it as its source. `unmapped`: nothing takes\nit. `unnamable`: its name makes no field name. `collides`: another attribute arrives under the same field\nname. `ignored`: the workspace said so."
      },
      "PersonStatus": {
        "type": "string",
        "title": "PersonStatus",
        "enum": [
          "active",
          "suspended",
          "removed"
        ],
        "description": "`active`; `suspended` in the directory; or `removed`, the recycle bin: gone from the directory, kept for\nthe connection's retention, and back as they were if the directory shows them again."
      },
      "FieldSettings": {
        "type": "object",
        "title": "FieldSettings",
        "required": [
          "fields",
          "offered",
          "people"
        ],
        "additionalProperties": false,
        "properties": {
          "people": {
            "type": "integer",
            "minimum": 0,
            "description": "Active people, for reading `FieldSetting.people` against."
          },
          "fields": {
            "type": "array",
            "description": "Every field, switched on or off, in the order Settings -> Fields shows them.",
            "items": {
              "$ref": "#/components/schemas/FieldSetting"
            }
          },
          "offered": {
            "type": "array",
            "description": "Fields the directory supplied at its last read that this workspace has not defined, whose values are dropped until it does.",
            "items": {
              "$ref": "#/components/schemas/OfferedField"
            }
          },
          "attributes": {
            "type": "array",
            "description": "The directory's own attributes at its latest full read, the customer's and not the provider's: what *Filled from...* offers.",
            "items": {
              "$ref": "#/components/schemas/ReadAttribute"
            }
          },
          "sources": {
            "type": "array",
            "description": "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.",
            "items": {
              "$ref": "#/components/schemas/ReadSelector"
            }
          },
          "sourcePeople": {
            "type": "integer",
            "minimum": 0,
            "description": "The people that read counted, what `sources[].holders` is out of."
          }
        },
        "description": "The workspace's fields, and what its directory offers that no field takes yet."
      },
      "FieldSetting": {
        "type": "object",
        "title": "FieldSetting",
        "required": [
          "name",
          "label",
          "kind",
          "multiValued",
          "source",
          "enabled",
          "people",
          "usedBy",
          "rules"
        ],
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "text",
              "phone",
              "url",
              "email",
              "date",
              "number",
              "boolean"
            ]
          },
          "multiValued": {
            "type": "boolean"
          },
          "source": {
            "type": "string",
            "enum": [
              "system",
              "custom"
            ],
            "description": "`system` is switched off, never removed; `custom` is this workspace's own."
          },
          "enabled": {
            "type": "boolean"
          },
          "people": {
            "type": "integer",
            "minimum": 0,
            "description": "Active people holding a value."
          },
          "usedBy": {
            "type": "array",
            "description": "The signatures that bind it, published or in a draft.",
            "items": {
              "$ref": "#/components/schemas/FieldUse"
            }
          },
          "rules": {
            "type": "integer",
            "minimum": 0,
            "description": "How many rules test it."
          },
          "filledFrom": {
            "$ref": "#/components/schemas/FieldSourceRef"
          },
          "suggestion": {
            "$ref": "#/components/schemas/FieldSourceRef"
          },
          "sourceChoosable": {
            "type": "boolean",
            "description": "Whether *Filled from...* is offered for it. Every field, while a Google or Microsoft directory is connected. Absent is false."
          },
          "defaultSources": {
            "type": "array",
            "description": "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.",
            "items": {
              "type": "string"
            }
          },
          "kept": {
            "type": "boolean",
            "description": "Kept in Ascripto: the directory fills it no more, and its values are what administrators set. Absent is false."
          },
          "fromDirectory": {
            "type": "integer",
            "minimum": 0,
            "description": "Active people whose value is the directory's, nobody having set one: who would lose it if the field were kept starting empty."
          },
          "key": {
            "type": "boolean",
            "description": "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."
          }
        },
        "description": "One field: how templates and this API name it, its kind, where its values come from, and who uses it."
      },
      "FieldUse": {
        "type": "object",
        "title": "FieldUse",
        "required": [
          "id",
          "name"
        ],
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          }
        }
      },
      "OfferedField": {
        "type": "object",
        "title": "OfferedField",
        "required": [
          "name",
          "seenAt"
        ],
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string"
          },
          "seenAt": {
            "type": "string",
            "format": "date-time"
          },
          "source": {
            "type": "string",
            "description": "The attribute it comes from, when one does."
          },
          "kind": {
            "type": "string",
            "enum": [
              "text",
              "phone",
              "url",
              "email",
              "date",
              "number",
              "boolean"
            ],
            "description": "The kind its values suggest, for defining it."
          },
          "multiValued": {
            "type": "boolean",
            "description": "Whether somebody holds several values."
          },
          "holders": {
            "type": "integer",
            "minimum": 0,
            "description": "People with a value."
          }
        }
      },
      "PublicPerson": {
        "type": "object",
        "title": "PublicPerson",
        "description": "One person: their names, each field with any value set in Ascripto and what applies, and their `version`.",
        "required": [
          "id",
          "email",
          "status",
          "displayName",
          "givenName",
          "familyName",
          "fields",
          "version",
          "changedAt"
        ],
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "email": {
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/PersonStatus"
          },
          "displayName": {
            "type": "string",
            "description": "As signatures use it: the value set in Ascripto, else the directory's. Empty when there is none."
          },
          "givenName": {
            "type": "string",
            "description": "As `displayName`, for the given name."
          },
          "familyName": {
            "type": "string",
            "description": "As `displayName`, for the family name."
          },
          "removedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When they left the directory; only while `status` is `removed`."
          },
          "fields": {
            "type": "array",
            "description": "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.",
            "items": {
              "$ref": "#/components/schemas/PublicPersonField"
            }
          },
          "version": {
            "type": "integer",
            "format": "int64",
            "description": "Moves on every real change to them: what `getPerson`'s `ETag` quotes and `patchPersonValues`' `If-Match` compares."
          },
          "changedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When `version` last moved."
          }
        }
      },
      "PublicPersonField": {
        "type": "object",
        "title": "PublicPersonField",
        "description": "One of a person's fields: any value set in Ascripto, and what applies.",
        "required": [
          "name",
          "value"
        ],
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string",
            "description": "The field's name, as templates bind it and `patchPersonValues` names it."
          },
          "value": {
            "type": "array",
            "description": "What applies: the value set in Ascripto when there is one, else the directory's. Empty when neither has one.",
            "items": {
              "type": "string"
            }
          },
          "override": {
            "type": "array",
            "description": "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.",
            "items": {
              "type": "string"
            }
          },
          "kept": {
            "type": "boolean",
            "description": "The field is kept in Ascripto: the directory never fills it, and `override` is simply its value. Absent is false."
          }
        }
      },
      "PublicPersonRow": {
        "type": "object",
        "title": "PublicPersonRow",
        "description": "One person, as `listPeople` lists them.",
        "required": [
          "id",
          "email",
          "name",
          "status",
          "version",
          "changedAt"
        ],
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "email": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "description": "The display name as signatures use it. Empty when there is none."
          },
          "status": {
            "$ref": "#/components/schemas/PersonStatus"
          },
          "removedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When they left the directory; only while `status` is `removed`."
          },
          "version": {
            "type": "integer",
            "format": "int64",
            "description": "Moves on every real change to them, as `getPerson`'s `version`."
          },
          "changedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When `version` last moved; what `changed_since` compares."
          }
        }
      },
      "PublicPeoplePage": {
        "type": "object",
        "title": "PublicPeoplePage",
        "description": "One page of people.",
        "required": [
          "people"
        ],
        "additionalProperties": false,
        "properties": {
          "people": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicPersonRow"
            }
          },
          "cursor": {
            "type": "string",
            "description": "The next page's; pass it as `cursor`. Absent on the last."
          }
        }
      },
      "PersonValuesPatch": {
        "type": "object",
        "title": "PersonValuesPatch",
        "description": "At least one of `values` and `names`; never the address.",
        "minProperties": 1,
        "additionalProperties": false,
        "properties": {
          "values": {
            "type": "object",
            "maxProperties": 200,
            "description": "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`.",
            "additionalProperties": {
              "type": "array",
              "maxItems": 100,
              "items": {
                "type": "string",
                "maxLength": 1000
              }
            }
          },
          "names": {
            "$ref": "#/components/schemas/PersonNamesPatch"
          }
        }
      },
      "PersonNamesPatch": {
        "type": "object",
        "title": "PersonNamesPatch",
        "description": "A person's names, each set as an override is: one left out is untouched, `\"\"` is nothing on purpose.",
        "additionalProperties": false,
        "properties": {
          "displayName": {
            "type": "string",
            "maxLength": 1000
          },
          "givenName": {
            "type": "string",
            "maxLength": 1000
          },
          "familyName": {
            "type": "string",
            "maxLength": 1000
          }
        }
      },
      "SheetFormat": {
        "type": "string",
        "title": "SheetFormat",
        "enum": [
          "xlsx",
          "csv",
          "json"
        ],
        "description": "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."
      },
      "PeopleImportApply": {
        "type": "string",
        "title": "PeopleImportApply",
        "enum": [
          "if-clean"
        ],
        "description": "`if-clean`: apply at once a batch with no problems that changes at most `PeopleImportWaiting.limit` people; hold any other as `waiting`."
      },
      "PeopleImportJson": {
        "type": "object",
        "title": "PeopleImportJson",
        "description": "An import as an API client sends it: the rows of a sheet, each a person and what to set.",
        "required": [
          "rows"
        ],
        "additionalProperties": false,
        "properties": {
          "rows": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100000,
            "items": {
              "$ref": "#/components/schemas/PeopleImportJsonRow"
            }
          }
        }
      },
      "PeopleImportJsonRow": {
        "type": "object",
        "title": "PeopleImportJsonRow",
        "description": "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.",
        "additionalProperties": false,
        "properties": {
          "key": {
            "type": "string",
            "maxLength": 1000
          },
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "email": {
            "type": "string",
            "maxLength": 320
          },
          "names": {
            "$ref": "#/components/schemas/PersonNamesPatch"
          },
          "values": {
            "type": "object",
            "maxProperties": 200,
            "description": "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`.",
            "additionalProperties": {
              "type": "array",
              "maxItems": 100,
              "items": {
                "type": "string",
                "maxLength": 1000
              }
            }
          }
        }
      },
      "PeopleImportWaiting": {
        "type": "object",
        "title": "PeopleImportWaiting",
        "description": "Why a batch sent with `apply=if-clean` was held.",
        "required": [
          "reasons",
          "limit",
          "changed"
        ],
        "additionalProperties": false,
        "properties": {
          "reasons": {
            "type": "array",
            "minItems": 1,
            "uniqueItems": true,
            "items": {
              "$ref": "#/components/schemas/PeopleImportWaitingReason"
            }
          },
          "limit": {
            "type": "integer",
            "minimum": 0,
            "description": "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": {
            "type": "integer",
            "minimum": 0,
            "description": "The people this one would change."
          }
        }
      },
      "PeopleImportWaitingReason": {
        "type": "string",
        "title": "PeopleImportWaitingReason",
        "enum": [
          "problems",
          "too-many"
        ],
        "description": "`problems`: the preview found some. `too-many`: it would change more than `limit` people."
      },
      "PeopleImport": {
        "type": "object",
        "title": "PeopleImport",
        "required": [
          "id",
          "file",
          "status",
          "at",
          "by",
          "rows",
          "people",
          "values",
          "overrides",
          "problems",
          "columns"
        ],
        "additionalProperties": false,
        "description": "A batch of values, a spreadsheet's or JSON's: what it would change, then what it did.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "file": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "preview",
              "applied",
              "undone",
              "expired",
              "waiting"
            ],
            "description": "`preview`: read, nothing written yet. `applied`. `undone`. `waiting`: sent with `apply=if-clean` and not\nclean, so held for an owner or an administrator to apply; `waiting` says why. `expired`: a preview or a\nwaiting batch older than 24 hours, which can no longer be applied."
          },
          "waiting": {
            "$ref": "#/components/schemas/PeopleImportWaiting"
          },
          "at": {
            "type": "string",
            "format": "date-time",
            "description": "When it was read."
          },
          "by": {
            "type": "string",
            "description": "Who sent it: a person's id, or the API client's id when `client` is present."
          },
          "client": {
            "$ref": "#/components/schemas/ApiClientRef",
            "description": "The API client that sent it."
          },
          "appliedAt": {
            "type": "string",
            "format": "date-time"
          },
          "appliedBy": {
            "type": "string"
          },
          "undoneAt": {
            "type": "string",
            "format": "date-time"
          },
          "undoneBy": {
            "type": "string"
          },
          "rows": {
            "type": "integer",
            "minimum": 0,
            "description": "Rows below the headings."
          },
          "people": {
            "type": "integer",
            "minimum": 0,
            "description": "People whose values it changes (changed, once applied)."
          },
          "values": {
            "type": "integer",
            "minimum": 0,
            "description": "Values it changes, one per person and field."
          },
          "overrides": {
            "type": "integer",
            "minimum": 0,
            "description": "Of `values`, those on a field the directory still fills -- an override each."
          },
          "changedSince": {
            "type": "integer",
            "minimum": 0,
            "description": "Applied or undone, the values left because they had moved meanwhile."
          },
          "columns": {
            "type": "array",
            "description": "The columns it read, by field, in the sheet's order; `id` and `email` included.",
            "items": {
              "type": "string"
            }
          },
          "problems": {
            "type": "object",
            "required": [
              "total",
              "first"
            ],
            "additionalProperties": false,
            "properties": {
              "total": {
                "type": "integer",
                "minimum": 0
              },
              "first": {
                "type": "array",
                "maxItems": 50,
                "items": {
                  "$ref": "#/components/schemas/PeopleImportProblem"
                }
              }
            }
          }
        }
      },
      "PeopleImportProblem": {
        "type": "object",
        "title": "PeopleImportProblem",
        "required": [
          "row",
          "code"
        ],
        "additionalProperties": false,
        "properties": {
          "row": {
            "type": "integer",
            "minimum": 1,
            "description": "The sheet's row number, the headings being 1; a JSON batch's row, its place in `rows` from 1."
          },
          "column": {
            "type": "string",
            "description": "The heading as written."
          },
          "code": {
            "$ref": "#/components/schemas/PeopleImportProblemCode"
          },
          "reason": {
            "$ref": "#/components/schemas/ValueRefusal"
          },
          "cell": {
            "type": "string",
            "description": "What the cell held, at most 200 characters."
          },
          "sameAs": {
            "type": "integer",
            "description": "For `same_person`, the row that matched them first."
          }
        }
      },
      "PeopleImportProblemCode": {
        "type": "string",
        "title": "PeopleImportProblemCode",
        "enum": [
          "no_person",
          "same_person",
          "one_value",
          "refused",
          "too_many",
          "too_long",
          "not_a_field",
          "ambiguous_key",
          "key_not_found"
        ],
        "description": "`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."
      },
      "Problem": {
        "type": "object",
        "title": "Problem",
        "description": "An RFC 9457 problem detail, which every error is. `type` names the problem: `https://ascripto.com/problems/`\nand a word, such as `permission`.",
        "required": [
          "type",
          "title",
          "status"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri",
            "description": "A URI identifying the problem type.",
            "default": "about:blank",
            "examples": [
              "https://ascripto.com/problems/tenant-suspended"
            ]
          },
          "title": {
            "type": "string",
            "description": "Short, human-readable summary. Stable for a given `type`.",
            "examples": [
              "Tenant suspended"
            ]
          },
          "status": {
            "type": "integer",
            "format": "int32",
            "description": "The HTTP status code, repeated in the body.",
            "minimum": 100,
            "maximum": 599,
            "examples": [
              403
            ]
          },
          "detail": {
            "type": "string",
            "description": "Human-readable explanation specific to this occurrence. Never carries a secret, a token, or an echo of a submitted credential."
          },
          "instance": {
            "type": "string",
            "format": "uri-reference",
            "description": "A URI identifying this specific occurrence."
          },
          "traceId": {
            "type": "string",
            "description": "Correlates this response with the server-side trace.",
            "examples": [
              "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01"
            ]
          }
        }
      },
      "ValueRefusedProblem": {
        "title": "ValueRefusedProblem",
        "description": "A `Problem`; when its `type` is `https://ascripto.com/problems/value-refused`, a value is not its field's\nkind, and `field` and `reason` say which (the first such) and why. Any other problem carries neither.",
        "allOf": [
          {
            "$ref": "#/components/schemas/Problem"
          },
          {
            "type": "object",
            "properties": {
              "field": {
                "type": "string",
                "description": "The field's name, as the request gave it."
              },
              "reason": {
                "$ref": "#/components/schemas/ValueRefusal"
              }
            }
          }
        ]
      },
      "ValueRefusal": {
        "type": "string",
        "title": "ValueRefusal",
        "enum": [
          "not_phone",
          "not_email",
          "not_web",
          "not_date",
          "not_number",
          "not_yes_no"
        ],
        "description": "Why a value is not its field's kind; text and addresses take anything. `not_phone`: digits,\n`+ ( ) . / -` and spaces, then an extension word and its digits if any, at least five digits.\n`not_email`: one bare address with a dotted host. `not_web`: http or https, or no scheme, with a dotted\nhost. `not_date`: `yyyy-MM-dd`. `not_number`: written with a dot. `not_yes_no`: true, false, yes or no."
      }
    }
  }
}
