find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/fallax-io:fallax-io-people-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: Fallax Io People API
  version: v1
  description: 'Operations tagged people across 2 of this provider''s published API definitions: fallax-io-openapi.json, fallax-io-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.fallax.io/v1
tags:
- name: People
paths:
  /people:
    get:
      operationId: listPeople
      summary: List people
      description: 'The directory: everyone this workspace can send a simulation to, with the status that decides whether it will. `syncedProvider` is set on anyone who came from a directory sync, and the fields that sync owns cannot be written through this API.'
      tags:
      - People
      security:
      - bearerAuth: []
      x-scope: read
      parameters:
      - schema:
          type: string
          description: Rows per page, 1 to 200. Defaults to 50. A page comes back with a `nextCursor` when there are more.
          example: '50'
        required: false
        description: Rows per page, 1 to 200. Defaults to 50. A page comes back with a `nextCursor` when there are more.
        name: limit
        in: query
      - schema:
          type: string
          description: The `nextCursor` from the previous page. Paging is by cursor rather than by offset, so rows written while you page are never skipped.
        required: false
        description: The `nextCursor` from the previous page. Paging is by cursor rather than by offset, so rows written while you page are never skipped.
        name: cursor
        in: query
      - schema:
          type: string
          description: 'Only rows after this instant, exclusive. ISO 8601 or epoch milliseconds. This is the parameter a poll trigger uses: pass the timestamp of the newest row you have already handled.'
          example: '2026-09-07T12:00:00Z'
        required: false
        description: 'Only rows after this instant, exclusive. ISO 8601 or epoch milliseconds. This is the parameter a poll trigger uses: pass the timestamp of the newest row you have already handled.'
        name: since
        in: query
      - schema:
          type: string
          description: '`desc` (the default) for newest first, which is what a person reading a page wants. `asc` for oldest first, which is what anything resuming from a watermark wants: with `since` and a limit, an ascending page is the oldest rows you have not seen, so a backlog drains in order instead of the newest page hiding the rest.'
          enum:
          - desc
          - asc
        required: false
        description: '`desc` (the default) for newest first, which is what a person reading a page wants. `asc` for oldest first, which is what anything resuming from a watermark wants: with `since` and a limit, an ascending page is the oldest rows you have not seen, so a backlog drains in order instead of the newest page hiding the rest.'
        name: order
        in: query
      - schema:
          type: string
          description: '`active`, `excluded` or `archived`.'
          enum:
          - active
          - excluded
          - archived
        required: false
        description: '`active`, `excluded` or `archived`.'
        name: status
        in: query
      - schema:
          type: string
          description: Exact address match.
        required: false
        description: Exact address match.
        name: email
        in: query
      - schema:
          type: string
          description: Exact department match.
        required: false
        description: Exact department match.
        name: department
        in: query
      responses:
        '200':
          description: List people
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonPage'
        '400':
          description: A parameter or body field the API cannot use. The message names the field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No key, an unknown key, or one that has been revoked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: A read-only key was used on a write endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 'No such endpoint, or no such row in this workspace. The two are deliberately indistinguishable from outside: another workspace''s ids must not be probeable.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: The path exists but not with that verb. `Allow` lists the verbs that work.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: More than 120 requests in a minute on one key. `Retry-After` says how long to wait. A poll every minute, and the paging behind it, is nowhere near this.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Our fault. Safe to retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: upsertPerson
      summary: Add or update a person
      description: Create a person, or update the one that already has this address. Safe to call more than once with the same address, which is what makes it usable from an onboarding workflow that may retry.
      tags:
      - People
      security:
      - bearerAuth: []
      x-scope: write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonInput'
      responses:
        '200':
          description: Add or update a person
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonUpsert'
        '400':
          description: A parameter or body field the API cannot use. The message names the field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No key, an unknown key, or one that has been revoked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: A read-only key was used on a write endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 'No such endpoint, or no such row in this workspace. The two are deliberately indistinguishable from outside: another workspace''s ids must not be probeable.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: The path exists but not with that verb. `Allow` lists the verbs that work.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: More than 120 requests in a minute on one key. `Retry-After` says how long to wait. A poll every minute, and the paging behind it, is nowhere near this.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Our fault. Safe to retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.fallax.io/v1
  /people/{id}:
    get:
      operationId: getPerson
      summary: Get a person
      description: One person from the directory.
      tags:
      - People
      security:
      - bearerAuth: []
      x-scope: read
      parameters:
      - schema:
          type: string
          description: The id of the row.
          example: r_2f8c
        required: true
        description: The id of the row.
        name: id
        in: path
      responses:
        '200':
          description: Get a person
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
        '400':
          description: A parameter or body field the API cannot use. The message names the field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No key, an unknown key, or one that has been revoked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: A read-only key was used on a write endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 'No such endpoint, or no such row in this workspace. The two are deliberately indistinguishable from outside: another workspace''s ids must not be probeable.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: The path exists but not with that verb. `Allow` lists the verbs that work.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: More than 120 requests in a minute on one key. `Retry-After` says how long to wait. A poll every minute, and the paging behind it, is nowhere near this.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Our fault. Safe to retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      operationId: updatePerson
      summary: Update a person
      description: 'Change one person by id: the same fields as the endpoint above, all optional, with `null` to clear one. The address itself cannot be changed, so a person''s evidence trail stays attached to the address it was collected under. Sending `status: "archived"` is how an offboarding workflow takes somebody out of the programme.'
      tags:
      - People
      security:
      - bearerAuth: []
      x-scope: write
      parameters:
      - schema:
          type: string
          description: The id of the row.
          example: r_2f8c
        required: true
        description: The id of the row.
        name: id
        in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonPatch'
      responses:
        '200':
          description: Update a person
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
        '400':
          description: A parameter or body field the API cannot use. The message names the field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No key, an unknown key, or one that has been revoked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: A read-only key was used on a write endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 'No such endpoint, or no such row in this workspace. The two are deliberately indistinguishable from outside: another workspace''s ids must not be probeable.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: The path exists but not with that verb. `Allow` lists the verbs that work.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: More than 120 requests in a minute on one key. `Retry-After` says how long to wait. A poll every minute, and the paging behind it, is nowhere near this.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Our fault. Safe to retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.fallax.io/v1
components:
  schemas:
    PersonInput:
      type: object
      properties:
        email:
          type: string
          description: Required. The person's address.
          example: sam@acme.com
        firstName:
          anyOf:
          - type: string
          - type: 'null'
          description: Optional.
        lastName:
          anyOf:
          - type: string
          - type: 'null'
          description: Optional.
        department:
          anyOf:
          - type: string
          - type: 'null'
          description: Optional. Reporting and breakdowns group on this.
        position:
          anyOf:
          - type: string
          - type: 'null'
          description: Optional. Job title.
        locale:
          anyOf:
          - type: string
          - type: 'null'
          description: Optional BCP 47 tag, e.g. `nl-BE`. Decides which translation of a lure they are sent.
          example: nl-BE
        timezone:
          anyOf:
          - type: string
          - type: 'null'
          description: Optional IANA zone, e.g. `Europe/Brussels`. Decides what local time they are sent at.
          example: Europe/Brussels
        status:
          type: string
          enum:
          - active
          - excluded
          - archived
          description: '`active`, `excluded` (stays in the directory, never simulated, not billed) or `archived` (offboarded).'
      required:
      - email
    Person:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
        firstName:
          type:
          - string
          - 'null'
        lastName:
          type:
          - string
          - 'null'
        department:
          type:
          - string
          - 'null'
        position:
          type:
          - string
          - 'null'
        locale:
          type:
          - string
          - 'null'
        timezone:
          type:
          - string
          - 'null'
        status:
          type: string
          enum:
          - active
          - excluded
          - archived
        syncedProvider:
          type:
          - string
          - 'null'
        createdAt:
          type:
          - string
          - 'null'
          format: date-time
      required:
      - id
      - email
      - firstName
      - lastName
      - department
      - position
      - locale
      - timezone
      - status
      - syncedProvider
      - createdAt
    PersonPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Person'
        nextCursor:
          type:
          - string
          - 'null'
          description: Pass as `cursor` for the next page.
        hasMore:
          type: boolean
      required:
      - data
      - nextCursor
      - hasMore
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
              - unauthorized
              - forbidden
              - not_found
              - invalid_request
              - method_not_allowed
              - rate_limited
              - internal
            message:
              type: string
          required:
          - code
          - message
      required:
      - error
    PersonUpsert:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
        firstName:
          type:
          - string
          - 'null'
        lastName:
          type:
          - string
          - 'null'
        department:
          type:
          - string
          - 'null'
        position:
          type:
          - string
          - 'null'
        locale:
          type:
          - string
          - 'null'
        timezone:
          type:
          - string
          - 'null'
        status:
          type: string
          enum:
          - active
          - excluded
          - archived
        syncedProvider:
          type:
          - string
          - 'null'
        createdAt:
          type:
          - string
          - 'null'
          format: date-time
        created:
          type: boolean
      required:
      - id
      - email
      - firstName
      - lastName
      - department
      - position
      - locale
      - timezone
      - status
      - syncedProvider
      - createdAt
      - created
    PersonPatch:
      type: object
      properties:
        email:
          type: string
          description: The address this person already has. It cannot be changed here.
          example: sam@acme.com
        firstName:
          anyOf:
          - type: string
          - type: 'null'
          description: Optional.
        lastName:
          anyOf:
          - type: string
          - type: 'null'
          description: Optional.
        department:
          anyOf:
          - type: string
          - type: 'null'
          description: Optional. Reporting and breakdowns group on this.
        position:
          anyOf:
          - type: string
          - type: 'null'
          description: Optional. Job title.
        locale:
          anyOf:
          - type: string
          - type: 'null'
          description: Optional BCP 47 tag, e.g. `nl-BE`. Decides which translation of a lure they are sent.
          example: nl-BE
        timezone:
          anyOf:
          - type: string
          - type: 'null'
          description: Optional IANA zone, e.g. `Europe/Brussels`. Decides what local time they are sent at.
          example: Europe/Brussels
        status:
          type: string
          enum:
          - active
          - excluded
          - archived
          description: '`active`, `excluded` (stays in the directory, never simulated, not billed) or `archived` (offboarded).'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: flx_
      description: A workspace API key, created in Settings.
x-refined-from:
- fallax-io-openapi.json
- fallax-io-openapi.json