Joinways People API

openapi: 3.2.0
info:
  title: Joinways Public People API
  version: 1.15.0
  description: 'The Joinways REST API lets you read and manage your CRM and event data:

    events, quotes, invoices, companies, contacts, leads (requests), venues,

    catalog, tasks, reports and more. It is a **JSON over HTTPS** API described by

    this OpenAPI 3.1 document, served at `https://joinways.app/openapi.yaml`

    and rendered at `https://joinways.app/docs/api`. The same data is reachable from AI assistants through the Joinways MCP

    server (`https://mcp.joinways.app`, guide at

    `https://joinways.app/docs/claude-mcp`): both surfaces share the OAuth

    server, the tokens, the scopes, the role permissions and the services of

    the app, so a rule holds the same way in the app, in the REST API and in

    MCP. ## Authentication


    Every request needs a **Bearer token** in the `Authorization` header:


    ```

    Authorization: Bearer jw_xxxxxxxx

    ```


    Two token types work:


    - **API key** (`jw_…`): an owner or admin creates one from **Settings →

    Developers → API keys** in the workspace (guide:

    `https://joinways.app/docs/api-keys`). An API key acts as the member

    who created it: it carries the read and write scopes, and the **role

    permissions its creator holds now** in the workspace (see below; a

    creator who leaves the workspace takes the key''s access with them). It

    does not expire unless you set an expiry, and can be revoked at any

    time from the same page. - **OAuth 2.1 access token** (`jw_oat_…`): for apps acting on a user''s

    behalf (Authorization Code + PKCE S256, same flow as the MCP server). - Authorization endpoint `https://joinways.app/oauth/authorize`, token

    endpoint `https://joinways.app/api/oauth/token`, revocation

    `https://joinways.app/api/oauth/revoke` (RFC 7009), metadata

    `https://joinways.app/.well-known/oauth-authorization-server`. - **Clients**: register with Dynamic Client Registration

    (`POST /api/oauth/register`), or use an https URL as `client_id`

    (Client ID Metadata Document). - **Resource** (RFC 8707): send `resource=https://joinways.app/api/v1`

    on the authorization and token requests to bind the token to this API

    (a token bound to `https://mcp.joinways.app` is refused here, and the

    other way round). An unknown resource is refused with

    `invalid_target`. Protected resource metadata:

    `https://joinways.app/.well-known/oauth-protected-resource/api/v1`. - **Refresh**: a client registered with the `refresh_token` grant gets a

    refresh token (`jw_ort_…`) next to a **1 hour** access token. Each

    refresh rotates the refresh token (the old one stops working); a

    refresh token unused for 90 days expires. A client without the

    refresh grant gets a **30 day** access token and re-runs the flow. A refresh may ask for fewer scopes: only the new access token is

    narrowed. A user who left the workspace gets `invalid_grant` on

    refresh, and the whole token family is revoked. - **Granted scope** = requested ∩ supported (`mcp.read`, `mcp.write`)

    ∩ registered by the client. - The authorization response carries `iss` (RFC 9207). The consent

    screen shows the host of a metadata-document client, and warns when

    the `redirect_uri` is on another domain. - A workspace owner sees and revokes connected apps in **Settings →

    Developers → MCP → Connected apps**. A token is **bound to a single workspace**. You never pass an

    `account_id`: the workspace comes from the token. The API is part of

    the **Pro plan and the free trial**: a valid token of a workspace

    without either is refused with `403 forbidden`, `details.reason:

    plan_not_eligible`. Revocation takes effect within about a minute

    across our infrastructure. Tokens are stored hashed (SHA-256) and shown

    once. A `401` carries the RFC 6750 / RFC 9728 challenge:


    ```

    WWW-Authenticate: Bearer resource_metadata="https://joinways.app/.well-known/oauth-protected-resource/api/v1", scope="mcp.read mcp.write"

    ```


    ## Scopes


    | Scope | Grants |

    |---|---|

    | `mcp.read` | Every `GET` |

    | `mcp.write` | Every `POST`, `PATCH`, `PUT`, `DELETE`, and reading (it implies `mcp.read`) |


    API keys carry both scopes.'
  contact:
    name: Joinways
    url: https://joinways.app
  license:
    name: Proprietary
  x-logo:
    url: /images/marketing/logo-header.svg
    altText: Joinways
    href: https://joinways.app
servers:
- url: https://joinways.app/api/v1
  description: Production
security:
- bearerAuth: []
- oauth2:
  - mcp.read
  - mcp.write
tags:
- name: People
paths:
  /people:
    get:
      tags:
      - People
      summary: List contacts
      operationId: listPeople
      description: Contacts of the workspace, newest first, with their company (`companies`). **Role permission:** none (any member).
      security:
      - bearerAuth: []
      - oauth2:
        - mcp.read
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      - name: company_id
        in: query
        description: Only contacts of this company.
        schema:
          type: string
          format: uuid
      - name: q
        in: query
        description: 'Case-insensitive search: every word must appear in the first name, last name or email, so « Marie Dupont » and « dupont marie » both find Marie Dupont.'
        schema:
          type: string
      responses:
        '200':
          description: Page of contacts.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Paginated'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/Person'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
    post:
      tags:
      - People
      summary: Create a contact
      operationId: createPerson
      description: 'Creates a contact (email stored in lower case) and a timeline entry, with the app''s duplicate rules: a contact of the workspace with the same email (or the same phone and a matching name) is returned instead of a new one (`200`, `matched_existing: true`), its empty fields (name, phone, company, notes, job title) filled from the request, never overwritten. A platform or generic mailbox (`contact@…`, `noreply@…`, a booking platform''s address) is never stored as the contact''s email, and a phone of a workspace member or a platform is dropped. **Role permission:** `data.write`.'
      security:
      - bearerAuth: []
      - oauth2:
        - mcp.write
      x-required-permission: data.write
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonCreate'
      responses:
        '200':
          description: An existing contact matched the request (same email, or same phone and name); `matched_existing` is `true`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonCreated'
        '201':
          description: The created contact; `matched_existing` is `false`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonCreated'
        '400':
          $ref: '#/components/responses/BadRequest'
          description: Validation failed, `role` and `job_title` disagree, `company_id` is not a company of the workspace, or nothing is left to make a contact of.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
  /people/{id}:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      tags:
      - People
      summary: Get a contact
      operationId: getPerson
      description: The contact with its company (`companies`) and enrichment data. **Role permission:** none (any member).
      security:
      - bearerAuth: []
      - oauth2:
        - mcp.read
      responses:
        '200':
          description: The contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonDetail'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
    patch:
      tags:
      - People
      summary: Update a contact
      operationId: updatePerson
      description: Updates the given fields; changes of name, email, phone and company are written to the timeline. **Role permission:** `data.write`.
      security:
      - bearerAuth: []
      - oauth2:
        - mcp.write
      x-required-permission: data.write
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonUpdate'
      responses:
        '200':
          description: The updated contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonDetail'
        '400':
          $ref: '#/components/responses/BadRequest'
          description: Validation failed, no field given, `role` and `job_title` disagree, or `company_id` is not a company of the workspace.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
          description: A contact with this email already exists.
        '429':
          $ref: '#/components/responses/RateLimited'
    delete:
      tags:
      - People
      summary: Delete a contact
      operationId: deletePerson
      description: Deletes the contact for good. **Role permission:** `settings.manage`.
      security:
      - bearerAuth: []
      - oauth2:
        - mcp.write
      x-required-permission: settings.manage
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '204':
          description: Deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  headers:
    RateLimitLimit:
      description: Requests allowed in the current window (per workspace once authenticated, per IP before).
      schema:
        type: integer
        example: 600
    RateLimitReset:
      description: When the window resets (ISO 8601).
      schema:
        type: string
        format: date-time
        example: '2026-10-04T14:31:00.000Z'
    RateLimitRemaining:
      description: Requests left in the current window.
      schema:
        type: integer
        example: 0
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
        example: 12
  schemas:
    LeadErrorReason:
      type: string
      description: 'Leads: convert, merge, link, status, create.'
      enum:
      - lead_not_found
      - lead_locked
      - invalid_venue
      - invalid_dates
      - venue_locked
      - venue_unavailable
      - lead_linked_elsewhere
      - same_lead
      - not_found
      - lead_archived
      - both_converted
      - target_archived
      - target_rejected
      - target_event_closed
      - other_venue_event
      - access_denied
      - event_not_found
      - event_closed
      - lead_moved_concurrently
      - validation_requires_event
      - lead_deleted
    QuoteErrorReason:
      type: string
      description: '409 state refusals, 400 validation (`min_price` with `details.params`; `package_article`: the line is an article of a package, write the package line; `package_discount_amount`: a package takes a percent discount only), 402 plan.'
      enum:
      - platform_quote_read_only
      - platform_quote_delete_forbidden
      - platform_version_signed
      - quote_conflict
      - quote_changed
      - quote_locked
      - quote_signed
      - quote_cancelled
      - quote_not_cancellable
      - quote_has_active_invoice
      - quote_has_amendments
      - quote_superseded
      - amendment_in_flight
      - amendment_nested
      - parent_not_active
      - parent_not_signed
      - parent_fully_invoiced
      - invalid_status
      - not_a_platform_version
      - event_closed
      - event_archived
      - platform_quote_no_document
      - min_price
      - invalid_location_item
      - package_article
      - package_discount_amount
      - no_fields
      - db_rule
      - validation
      - quotes_plan_required
    SignedQuoteImportErrorReason:
      type: string
      description: POST /events/{id}/quotes/import.
      enum:
      - quotes_plan_required
      - event_not_found
      - quote_not_found
      - event_archived
      - quote_not_signable
      - duplicate_reference
      - invalid_pdf
      - invalid_amounts
      - pdf_too_large
      - forbidden
    PlatformErrorReason:
      type: string
      description: Authentication and rate limits (403, 429).
      enum:
      - plan_not_eligible
      - per-ip
      - per-account-minute
      - per-account-day
      - email_rate_limited
    PersonDetail:
      description: A contact with every stored field (`GET`, `PATCH`).
      allOf:
      - $ref: '#/components/schemas/Person'
      - type: object
        properties:
          account_id:
            type: string
            format: uuid
          email_shared:
            type: boolean
          source:
            type:
            - string
            - 'null'
          source_metadata:
            type:
            - object
            - 'null'
            additionalProperties: true
          external_id:
            type:
            - string
            - 'null'
          enrichment_data:
            type:
            - object
            - 'null'
            additionalProperties: true
    TaskErrorReason:
      type: string
      enum:
      - task_not_found
      - event_not_found
      - assignee_not_found
      - event_archived
      - no_fields
    ErrorReason:
      description: '`details.reason` of an error: snake_case lower case, the same value as the `code` of the matching MCP tool error. One list per domain.'
      anyOf:
      - $ref: '#/components/schemas/PlatformErrorReason'
      - $ref: '#/components/schemas/EventErrorReason'
      - $ref: '#/components/schemas/LeadErrorReason'
      - $ref: '#/components/schemas/TaskErrorReason'
      - $ref: '#/components/schemas/QuoteErrorReason'
      - $ref: '#/components/schemas/CatalogErrorReason'
      - $ref: '#/components/schemas/SignedQuoteImportErrorReason'
      - $ref: '#/components/schemas/EmailErrorReason'
    PersonUpdate:
      type: object
      description: Every field is optional; at least one is required.
      properties:
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
        company_id:
          type: string
          format: uuid
        notes:
          type: string
        job_title:
          type: string
        role:
          type: string
          description: Same as `job_title`.
    Person:
      type: object
      description: A contact, optionally linked to a company.
      properties:
        id:
          type: string
          format: uuid
        first_name:
          type:
          - string
          - 'null'
          example: Jane
        last_name:
          type:
          - string
          - 'null'
          example: Doe
        email:
          type:
          - string
          - 'null'
          example: jane@acme.com
        phone:
          type:
          - string
          - 'null'
        role:
          type:
          - string
          - 'null'
          description: Job title (stored name).
          example: Head of Events
        job_title:
          type:
          - string
          - 'null'
          description: Job title, same value as `role`.
          example: Head of Events
        company_id:
          type:
          - string
          - 'null'
          format: uuid
        companies:
          type:
          - object
          - 'null'
          description: The company (list and `GET` only).
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
        notes:
          type:
          - string
          - 'null'
        enrichment_status:
          type:
          - string
          - 'null'
        enrichment_completed_at:
          type:
          - string
          - 'null'
          format: date-time
        created_at:
          type:
          - string
          - 'null'
          format: date-time
        updated_at:
          type:
          - string
          - 'null'
          format: date-time
    PersonCreated:
      description: 'The contact a `POST /people` landed on: created (`201`) or an existing one matched by the duplicate rules (`200`).'
      allOf:
      - $ref: '#/components/schemas/PersonDetail'
      - type: object
        required:
        - matched_existing
        properties:
          matched_existing:
            type: boolean
            description: true when an existing contact (same email, or same phone and name) was returned instead of a new one.
    EventErrorReason:
      type: string
      description: Events, their sub-resources and the BEO.
      enum:
      - event_not_found
      - event_archived
      - event_not_archived
      - event_has_dependencies
      - venue_locked
      - venue_required
      - venue_unavailable
      - invalid_venue_spaces
      - invalid_dates
      - invalid_timezone
      - invalid_reference
      - invalid_assignee
      - invalid_stage
      - platform_duplicate
      - no_fields
      - revenue_access_required
      - version_conflict
    CatalogErrorReason:
      type: string
      description: 'Catalog writes, packages mostly. All `400` except `package_component` (`409`). `package_price_read_only`: the price and tax rate of a package come from its components, they are never sent (nor `pricing_mode` without `components`). `package_components_required`: a package needs at least one component (or `is_package: false`). `package_flag_required`: `components` sent for a plain item without `is_package: true`. `package_component_duplicate`: an item listed twice. `package_component_self`: the package among its own components. `package_component_not_found`: a component that is not an item of the package''s venue (unknown, another venue, another workspace). `package_component_is_package`: a package cannot contain a package. `package_component_vat_required`: a component has no tax rate and the venue no country to take one from. `package_price_zero`: the components add up to 0. `min_price_above_price`: `min_price` above the price of the package. `price_required`: a plain item (created, or a package turned back into one) without a price. `package_components_refused`: the database refused the composition (a rule above, lost to a concurrent change). `package_component` (409): the item is a component of a package; it cannot be deleted, nor become a package, before it is removed from that package.'
      enum:
      - package_price_read_only
      - package_components_required
      - package_flag_required
      - package_component_duplicate
      - package_component_self
      - package_component_not_found
      - package_component_is_package
      - package_component_vat_required
      - package_price_zero
      - min_price_above_price
      - price_required
      - package_components_refused
      - package_component
    Error:
      type: object
      description: Standard error envelope returned on any non-2xx response.
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: Stable machine-readable error code (see the Errors table).
              enum:
              - invalid_request
              - unauthorized
              - payment_required
              - forbidden
              - not_found
              - conflict
              - idempotency_conflict
              - payload_too_large
              - idempotency_key_reuse
              - quota_exceeded
              - rate_limited
              - server_error
              example: not_found
            message:
              type: string
              description: Human-readable message (do not parse it). Generic on 5xx.
              example: Event not found
            details:
              description: 'Structured details: field errors on validation (`formErrors`, `fieldErrors`), the query parameter at fault (`field`), `reason` (a stable code) on refusals, or `null`.'
              oneOf:
              - type: object
                additionalProperties: true
                properties:
                  reason:
                    $ref: '#/components/schemas/ErrorReason'
                  field:
                    type: string
                    description: The parameter or body field at fault.
              - type: 'null'
    PersonCreate:
      type: object
      required:
      - first_name
      - last_name
      properties:
        first_name:
          type: string
          minLength: 1
          example: Jane
        last_name:
          type: string
          minLength: 1
          example: Doe
        email:
          type: string
          format: email
          example: jane@acme.com
        phone:
          type: string
        company_id:
          type: string
          format: uuid
        notes:
          type: string
        job_title:
          type: string
          example: Head of Events
        role:
          type: string
          description: Same as `job_title` (send one; both must agree).
    EmailErrorReason:
      type: string
      description: POST /events/{id}/emails.
      enum:
      - event_not_found
      - event_archived
      - connection_not_found
      - connection_inactive
      - connection_cannot_send
      - no_connection
      - reconnect_required
      - email_rate_limited
    Paginated:
      type: object
      description: Envelope wrapping a page of results.
      required:
      - data
      - pagination
      properties:
        data:
          type: array
          description: The page of results (item type depends on the endpoint).
          items: {}
        pagination:
          type: object
          required:
          - page
          - per_page
          - total
          - total_pages
          properties:
            page:
              type: integer
              description: Current 1-based page.
              example: 1
            per_page:
              type: integer
              description: Items per page.
              example: 50
            total:
              type:
              - integer
              - 'null'
              description: Total matching items across all pages (`null` only on a page past the last one, when unknown).
              example: 1234
            total_pages:
              type:
              - integer
              - 'null'
              example: 25
  responses:
    Conflict:
      description: The state of the record refuses the operation (`conflict`). `details.reason` is a stable code.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing, invalid, expired or revoked bearer token (`unauthorized`).
      headers:
        WWW-Authenticate:
          description: RFC 6750 challenge pointing at the protected resource metadata (RFC 9728).
          schema:
            type: string
          example: Bearer resource_metadata="https://joinways.app/.well-known/oauth-protected-resource/api/v1", scope="mcp.read mcp.write"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: unauthorized
              message: Invalid or expired token
              details: null
    NotFound:
      description: Not found in this workspace, or the id of the path is not a UUID (`not_found`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: not_found
              message: Event not found
              details: null
    Forbidden:
      description: '`forbidden`: the token lacks the scope, its owner''s role lacks the permission named by the operation, or the workspace has neither the Pro plan nor a trial (`details.reason` `plan_not_eligible`).'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: forbidden
              message: 'Missing required permission: quotes.manage'
              details: null
    RateLimited:
      description: 'Too many requests (`rate_limited`). `details.reason`: `per-ip`, `per-account-minute`, `per-account-day`, or `email_rate_limited` (email budget). Always carries `Retry-After`: wait that many seconds.'
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: rate_limited
              message: Too many requests
              details:
                reason: per-account-minute
    BadRequest:
      description: Validation failed (`invalid_request`). For a body that fails the schema, `details` holds `formErrors` and `fieldErrors`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: invalid_request
              message: Validation failed
              details:
                formErrors: []
                fieldErrors:
                  start_date:
                  - Required
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: 'Optional client-generated key (1 to 255 characters, e.g. a UUID v4) that makes the request idempotent for 24 hours: a retry with the same key replays the recorded response (marked `Idempotency-Replayed: true`) instead of executing the operation again. Same key with another body: `422 idempotency_key_reuse`; while the first request runs: `409 idempotency_conflict`. See the **Idempotency** section.

        '
      schema:
        type: string
        minLength: 1
        maxLength: 255
      example: 5b0c6f1e-2f4a-4c1e-9d3b-7a2e8f0c1d23
    PerPage:
      name: per_page
      in: query
      description: Items per page.
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 50
    Page:
      name: page
      in: query
      description: 1-based page number.
      schema:
        type: integer
        minimum: 1
        default: 1
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key or OAuth token
      description: 'Paste a token in the `Authorization: Bearer …` header: an **API key** (`jw_…`, created in Settings → Developers → API keys, acting with the role of the member who created it) or an **OAuth 2.1 access token** (`jw_oat_…`). A token is bound to a single workspace.

        '
    oauth2:
      type: oauth2
      description: 'OAuth 2.1 authorization code grant with mandatory PKCE (S256). Access tokens are opaque strings prefixed `jw_oat_`, presented as `Authorization: Bearer …`: valid 1 hour with a refresh token (`jw_ort_…`, rotated on each use, 90 days idle), 30 days for a client without the refresh grant. Send `resource=https://joinways.app/api/v1` (RFC 8707). Clients register dynamically or use an https `client_id` (Client ID Metadata Document). Tokens are bound to a single workspace.

        '
      flows:
        authorizationCode:
          authorizationUrl: https://joinways.app/oauth/authorize
          tokenUrl: https://joinways.app/api/oauth/token
          refreshUrl: https://joinways.app/api/oauth/token
          scopes:
            mcp.read: Read the workspace data the member's role can read.
            mcp.write: Create, update, delete and actions within the member's role (implies read).