OK Capsule

OK Capsule Consumers API

Routes to manage consumers

Documentation GitHub OpenAPI

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

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/ok-capsule-consumers-api"

All apis

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

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no email required.

GitHub Google LinkedIn

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

OpenAPI Specification

openapi: 3.2.0
info:
  description: '## Overview


    The OK Capsule API enables you to programmatically create supplement orders, manage consumers, and track shipments. It is a REST API that accepts JSON requests, returns JSON responses, and uses standard HTTP methods and status codes.


    **All requests must be made over HTTPS.**


    📚 **Additional Resources:** [Getting Started Guide](https://docs.okcapsule.app/docs/getting-started) | [Recipes & Examples](https://docs.okcapsule.app/docs/category/recipes)


    ## Getting Started


    > **New to OK Capsule API?** Account and brand setup must be completed before contacting OK Capsule about API credentials. If you have not set up your account and brand yet, start with the [Getting Started Guide](https://docs.okcapsule.app/docs/getting-started) before proceeding.


    1. **Set up your account** - Your OK Capsule account must be created and active

    2. **Set up your brand** - At least one Product Line must be configured in your account

    3. **Contact OK Capsule about API credentials** - Reach out to your OK Capsule representative once account and brand setup are complete

    4. **Authenticate** - POST to `/v2/authentication/token` to get an access token

    5. **List products** - GET `/v2/products` to see available supplements

    6. **Create an order** - POST to `/v2/orders` with consumer and product details

    7. **Track fulfillment** - Monitor order status and shipping via `/v2/orders` and `/v2/fulfillments`


    ## Environments


    | Environment | Purpose | Notes |

    |-------------|---------|-------|

    | **Production** | Live orders | Real fulfillment and shipping |

    | **Stage** | Testing | Test data only, no real shipments |


    ⚠️ Users and data are environment-specific. Stage credentials do not work in Production.


    ## Core Concepts


    | Term | Route | Description |

    |------|-------|-------------|

    | **Client** | `/v2/clients` | Your organization (business partner submitting orders) |

    | **Consumer** | `/v2/consumers` | Your end customer who receives supplements |

    | **Product** | `/v2/products` | A client-specific instance of an OKC Product with custom branding |

    | **Order** | `/v2/orders` | A request to fulfill supplements for a consumer |

    | **Order Line** | — | A set of pouches within an order (e.g., 30-day supply) |

    | **Pouch** | — | An individual daily packet of supplements |

    | **Fulfillment** | `/v2/fulfillments` | Shipping, tracking, and delivery information for an order |

    | **Assembly** | `/v2/assemblies` | A client''s predefined bundle of products (commonly called a "pack") |

    | **Product Line** | `/v2/product-lines` | A client''s marketing brand (appears on packaging) |

    | **OKC Product** | — | A supplement in the OK Capsule master catalog (what OKC purchases from vendors) |

    | **User** | `/v2/users` | An authorized person who accesses the API or portal |

    | **Contact** | `/v2/contacts` | A person associated with a client, managed for communication purposes |'
  version: 2.0.0
  title: OKC core API V2 Consumers API
  contact:
    name: Engineering Department, OKCapsule
    email: lukas@okcapsule.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- description: Production environment
  url: https://na1-prod.okcapsule.app
- description: Stage/Testing environment
  url: https://na1-stage.okcapsule.app
tags:
- name: Consumers
  description: Routes to manage consumers
paths:
  /v2/consumers:
    post:
      tags:
      - Consumers
      security:
      - bearerAuth:
        - consumers/write
      summary: Creates a consumer.
      operationId: createConsumer
      description: Creates a consumer record.
      parameters:
      - in: query
        name: q
        description: For internal users only. Use Query DSL *query_string* syntax to send client id.
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              - first_name
              - last_name
              properties:
                email:
                  type: string
                  format: email
                  maxLength: 100
                  example: user@example.com
                first_name:
                  type: string
                  maxLength: 100
                  example: John
                last_name:
                  type: string
                  maxLength: 100
                  example: Doe
                phone_number:
                  type:
                  - string
                  - 'null'
                  format: E.164
                  maxLength: 15
                  example: '+12133734253'
                client_custom_consumer_id:
                  type:
                  - string
                  - 'null'
                  example: ABCDE98765-789-89
                crm_account_id:
                  type:
                  - string
                  - 'null'
                  x-internal: true
                  description: Internal use only - filtered out for client users.
                  example: oAISOURS
                crm_id:
                  type:
                  - string
                  - 'null'
                  x-internal: true
                  description: Internal use only - filtered out for client users.
                  example: 12523-ABC-9874
            examples:
              ConsumerCompleteSample:
                $ref: '#/components/examples/ConsumerFullSample'
              ConsumerSample:
                $ref: '#/components/examples/ConsumerRequiredSample'
      responses:
        '201':
          description: Returns a created Consumer object.
          content:
            application/json:
              schema:
                type: object
                properties:
                  consumer:
                    $ref: '#/components/schemas/Consumer'
        '422':
          $ref: '#/components/responses/422ValidationError'
        default:
          $ref: '#/components/responses/UnknownError'
    get:
      tags:
      - Consumers
      security:
      - bearerAuth:
        - consumers/read
      summary: List all consumers.
      operationId: listConsumers
      description: "List all consumers.\n\n  Filterable fields:\n  * email\n  * first_name\n  * last_name\n  * crm_account_id\n  * crm_id\n  * client_custom_consumer\n  \n  Sortable fields:\n  * first_name\n  * last_name\n"
      parameters:
      - $ref: '#/components/parameters/LimitParameters'
      - $ref: '#/components/parameters/CursorParameters'
      - $ref: '#/components/parameters/SortByParameters'
      - $ref: '#/components/parameters/QueryParameters'
      responses:
        '200':
          description: search results matching criteria
          content:
            application/json:
              schema:
                required:
                - consumers
                properties:
                  consumers:
                    type: array
                    items:
                      $ref: '#/components/schemas/Consumer'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Error response.
  /v2/consumers/count:
    get:
      tags:
      - Consumers
      security:
      - bearerAuth:
        - consumers/read
      summary: Count of all consumers
      operationId: getConsumerTotalCount
      description: "Count of all consumers.\n\n Filterable fields:\n   * email\n   * first_name\n   * last_name\n"
      parameters:
      - $ref: '#/components/parameters/QueryParameters'
      responses:
        '200':
          description: Search results matching criteria
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/Count'
        default:
          $ref: '#/components/responses/UnknownError'
  /v2/consumers/{id}:
    get:
      tags:
      - Consumers
      security:
      - bearerAuth:
        - consumers/read
      summary: Retrieve a consumer
      operationId: getConsumer
      description: Retrieve a consumer by id
      parameters:
      - $ref: '#/components/parameters/IdParameter'
      - in: query
        name: q
        description: For internal users only. Use Query DSL *query_string* syntax to send client id.
        schema:
          type: string
      responses:
        '200':
          description: Returns the Consumer object for a valid identifier.
          content:
            application/json:
              schema:
                type: object
                properties:
                  consumer:
                    $ref: '#/components/schemas/Consumer'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Error response.
    put:
      tags:
      - Consumers
      security:
      - bearerAuth:
        - consumers/write
      summary: Update a consumer
      operationId: updateConsumer
      description: Update a consumer
      parameters:
      - $ref: '#/components/parameters/IdParameter'
      - in: query
        name: q
        description: For internal users only. Use Query DSL *query_string* syntax to send client id.
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  maxLength: 100
                  example: user@example.com
                first_name:
                  type: string
                  maxLength: 100
                  example: John
                last_name:
                  type:
                  - string
                  - 'null'
                  maxLength: 100
                  example: Doe
                phone_number:
                  type:
                  - string
                  - 'null'
                  format: E.164
                  maxLength: 15
                  example: '+12133734253'
                client_custom_consumer_id:
                  type:
                  - string
                  - 'null'
                  example: ABCDE98765-789-89
                crm_account_id:
                  type:
                  - string
                  - 'null'
                  x-internal: true
                  description: Internal use only - filtered out for client users.
                  example: oAISOURS
                crm_id:
                  type:
                  - string
                  - 'null'
                  x-internal: true
                  description: Internal use only - filtered out for client users.
                  example: 12523-ABC-9874
      responses:
        '200':
          description: Returns the updated Consumer object.
          content:
            application/json:
              schema:
                type: object
                properties:
                  consumer:
                    $ref: '#/components/schemas/Consumer'
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
          description: Validation error response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Error response.
    delete:
      tags:
      - Consumers
      security:
      - bearerAuth:
        - consumers/write
      summary: Delete a consumer
      operationId: deleteConsumer
      description: Delete a consumer.
      parameters:
      - $ref: '#/components/parameters/IdParameter'
      - in: query
        name: q
        description: For internal users only. Use Query DSL *query_string* syntax to send client id.
        schema:
          type: string
      responses:
        '204':
          $ref: '#/components/responses/204ConfirmDeletion'
components:
  parameters:
    SortByParameters:
      in: query
      name: sort_by
      description: Sort values by a specific property. See available sort by values in the table.
      schema:
        type: string
    QueryParameters:
      in: query
      name: q
      description: Use Query DSL *query_string* syntax
      schema:
        type: string
    LimitParameters:
      in: query
      name: limit
      description: Number of results to return. Default 50, max 250.
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 250
    CursorParameters:
      in: query
      name: cursor
      description: Return results before/after a specific record.
      schema:
        type: string
    IdParameter:
      in: path
      name: id
      required: true
      schema:
        type: string
        minimum: 1
  examples:
    ConsumerFullSample:
      summary: Creates a consumer.
      value:
        email: peter_parker@example.com
        first_name: Peter
        last_name: Parker
        phone_number: 805-708-9847
        client_custom_consumer_id: ABCDE98765-789-89
    ConsumerRequiredSample:
      summary: Creates a consumer with only the required fields.
      value:
        email: john@example.com
        first_name: John
        last_name: Doe
  responses:
    422ValidationError:
      description: Validation error response.
      content:
        application/json:
          schema:
            type: object
            title: Validation Error
            required:
            - message
            - errors
            description: A validation error response from the OK Capsule API (Joi validation)
            properties:
              message:
                description: A human-readable message indicating a validation error occurred.
                maxLength: 40000
                type: string
                example: Validation error
              errors:
                description: An array of validation errors from Joi schema validation
                type: array
                items:
                  type: object
                  required:
                  - message
                  - type
                  properties:
                    message:
                      description: A human-readable message providing more details about the validation error.
                      type: string
                      example: '''business_name'' is required'
                    type:
                      description: The Joi validation type that failed.
                      type: string
                      example: any.required
    204ConfirmDeletion:
      description: Confirms resource deletion.
    UnknownError:
      description: Error response.
      content:
        application/json:
          schema:
            title: Error Model
            description: An error response from the OK Capsule API
            type: object
            properties:
              error:
                title: Error Model Content
                type: object
                description: Error details object
                required:
                - message
                properties:
                  errorCode:
                    description: For some errors that could be handled programmatically, a short string indicating the error code.
                    maxLength: 5000
                    type: string
                    example: RESOURCE_NOT_FOUND
                  message:
                    description: A human-readable message providing more details about the error.
                    maxLength: 40000
                    type: string
                    example: The requested resource was not found
              message:
                description: Top-level error message (present in some error responses)
                type: string
                example: Internal Server Error
            required:
            - error
  schemas:
    ValidationError:
      type: object
      title: Validation Error
      required:
      - message
      - errors
      description: A validation error response from the OK Capsule API (Joi validation)
      properties:
        message:
          description: A human-readable message indicating a validation error occurred.
          maxLength: 40000
          type: string
          example: Validation error
        errors:
          description: An array of validation errors from Joi schema validation
          type: array
          items:
            type: object
            required:
            - message
            - type
            properties:
              message:
                description: A human-readable message providing more details about the validation error.
                type: string
                example: '''business_name'' is required'
              type:
                description: The Joi validation type that failed.
                type: string
                example: any.required
    Consumer:
      allOf:
      - allOf:
        - type: object
          required:
          - created_at
          - updated_at
          properties:
            created_at:
              type: string
              format: date-time
              readOnly: true
              example: '2023-03-20T09:12:28Z'
            updated_at:
              type: string
              format: date-time
              readOnly: true
              example: '2023-03-20T09:12:28Z'
        - type: object
          required:
          - id
          - client_id
          properties:
            id:
              type: string
              format: uuid
              readOnly: true
              example: d290f1ee-6c54-4b01-90e6-d701748f0898
            client_id:
              type: string
              format: uuid
              example: d290f1ee-6c54-4b01-90e6-d701748f0851
            email:
              type: string
              format: email
              example: user@example.com
            first_name:
              type: string
              example: John
            last_name:
              type: string
              example: Doe
            phone_number:
              type: string
              format: E.164
              example: '+12133734253'
            client_custom_consumer_id:
              type: string
              example: ABCDE98765-789-89
            crm_account_id:
              type: string
              x-internal: true
              description: Internal use only.
              example: oIAD8996SJSJ
            crm_id:
              type: string
              x-internal: true
              description: Internal use only.
              example: 12523-ABC-9874
      - type: object
        required:
        - created_at
        - updated_at
        properties:
          created_at:
            type: string
            format: date-time
            readOnly: true
            example: '2023-03-20T09:12:28Z'
          updated_at:
            type: string
            format: date-time
            readOnly: true
            example: '2023-03-20T09:12:28Z'
    Count:
      allOf:
      - type: object
        properties:
          count:
            type: number
            example: 8
    ErrorModel:
      title: Error Model
      description: An error response from the OK Capsule API
      type: object
      properties:
        error:
          title: Error Model Content
          type: object
          description: Error details object
          required:
          - message
          properties:
            errorCode:
              description: For some errors that could be handled programmatically, a short string indicating the error code.
              maxLength: 5000
              type: string
              example: RESOURCE_NOT_FOUND
            message:
              description: A human-readable message providing more details about the error.
              maxLength: 40000
              type: string
              example: The requested resource was not found
        message:
          description: Top-level error message (present in some error responses)
          type: string
          example: Internal Server Error
      required:
      - error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT