# Create a custom API integration (/docs/api-reference/integrations/createCustomApiIntegration)

> Save a call to your own HTTP endpoint as an integration. Attach it to an agent with `attachAgentIntegration`, and the agent calls the endpoint during a call when the conversation needs it, then uses the response in its reply. Parameters marked `isLLMGenerated` are filled in by the agent from the conversation.

**POST** `/integrations/custom-api`

Save a call to your own HTTP endpoint as an integration. Attach it to an agent with `attachAgentIntegration`, and the agent calls the endpoint during a call when the conversation needs it, then uses the response in its reply. Parameters marked `isLLMGenerated` are filled in by the agent from the conversation.

```yaml
operationId: createCustomApiIntegration
requestBody:
  required: true
  content:
    application/json:
      schema:
        type: object
        required:
          - name
          - url
          - method
        properties:
          user_id:
            type: integer
            description: |
              Reseller keys only: act as one of your clients by its user id. Omit
              it to act on your own account.
              [How acting for a client works](/docs/reseller/your-clients/acting-as-clients).
            example: 1234
          name:
            type: string
            description: A name for the integration.
          description:
            type: string
            description: |
              What the endpoint does. The agent reads this to decide
              when to call it, so say what it returns and when it is useful.
          url:
            type: string
            format: uri
          method:
            type: string
            enum:
              - GET
              - POST
              - PUT
              - PATCH
              - DELETE
          headers:
            type: array
            description: Fixed headers sent on every request.
            items:
              type: object
              required:
                - key
                - value
              properties:
                key:
                  type: string
                value:
                  type: string
          query_params:
            type: array
            description: Query string parameters.
            items:
              type: object
              description: |
                One query or body parameter of a custom API. With `isLLMGenerated`
                true the agent fills the value from the conversation, guided by
                `description`. With it false, the text in `description` is sent as a
                fixed value.
              required:
                - key
              properties:
                key:
                  type: string
                  description: The parameter name your endpoint expects.
                description:
                  type: string
                  description: >-
                    What the agent should put here, or the fixed value when `isLLMGenerated` is
                    false.
                type:
                  type: string
                  enum:
                    - string
                    - number
                    - boolean
                    - object
                    - array
                  default: string
                required:
                  type: boolean
                  description: Whether the agent must supply this parameter.
                isLLMGenerated:
                  type: boolean
                  default: true
                  description: Let the agent fill this value from the conversation.
                children:
                  type: array
                  description: >-
                    Nested fields of an `object` or `array` body parameter. Query parameters have no
                    children.
                  items: {}
          body_params:
            type: array
            description: |
              Request body fields, sent as JSON. A GET request sends no
              body. Every request with a body also carries the call's
              `from_number`, `to_number` and `call_sid`.
            items:
              type: object
              description: |
                One query or body parameter of a custom API. With `isLLMGenerated`
                true the agent fills the value from the conversation, guided by
                `description`. With it false, the text in `description` is sent as a
                fixed value.
              required:
                - key
              properties:
                key:
                  type: string
                  description: The parameter name your endpoint expects.
                description:
                  type: string
                  description: >-
                    What the agent should put here, or the fixed value when `isLLMGenerated` is
                    false.
                type:
                  type: string
                  enum:
                    - string
                    - number
                    - boolean
                    - object
                    - array
                  default: string
                required:
                  type: boolean
                  description: Whether the agent must supply this parameter.
                isLLMGenerated:
                  type: boolean
                  default: true
                  description: Let the agent fill this value from the conversation.
                children:
                  type: array
                  description: >-
                    Nested fields of an `object` or `array` body parameter. Query parameters have no
                    children.
                  items: {}
          request_timeout:
            type: integer
            default: 10
            description: Seconds to wait for your endpoint before the agent moves on.
      example:
        name: Order status
        description: Look up an order's delivery status by order number.
        url: https://api.acme-corp.io/orders/status
        method: GET
        headers:
          - key: Authorization
            value: Bearer YOUR_TOKEN
        query_params:
          - key: order_number
            description: The order number the caller reads out
            type: string
            required: true
            isLLMGenerated: true
responses:
  '200':
    description: The integration was created.
    content:
      application/json:
        schema:
          type: object
          properties:
            success:
              type: boolean
            message:
              type: string
            integration_id:
              type: integer
              description: Use it as `integration_id` to attach the integration to an agent.
            integration:
              type: object
              description: The new integration. Stored credentials read `********`.
              additionalProperties: true
              properties:
                id:
                  type: integer
                  description: Use it as `integration_id` in a post-call action.
                name:
                  type: string
                integration_type:
                  type: string
                  description: The kind of integration.
                  example: google_sheets
                user_id:
                  type: integer
                user_name:
                  type: string
                organization_id:
                  type: integer
                organization_name:
                  type: string
  '400':
    description: |
      The integration was not created: a required field is missing, the
      name is taken by another integration, or a value is the hidden
      `********` copied from a listing.
    content:
      application/json:
        schema:
          type: object
          properties:
            error:
              type: string
              example: invalid_request
            error_description:
              type: string
              example: An integration with this name already exists in your organization
  '401':
    description: Missing or invalid API key.
  '403':
    description: The API key's user cannot make changes to integrations.
```

**Python SDK**

```python
from omnidimension import Client
client = Client(api_key)

response = client.integrations.create_custom_api_integration(
    name="Order status",
    description="Look up an order's delivery status by order number.",
    url="https://api.acme-corp.io/orders/status",
    method="GET",
    headers=[{"key": "Authorization", "value": "Bearer YOUR_TOKEN"}],
    query_params=[{
        "key": "order_number",
        "description": "The order number the caller reads out",
        "type": "string",
        "required": True,
        "isLLMGenerated": True,
    }],
)
print(response["json"]["integration_id"])
```

**curl**

```bash
curl -X POST "https://omnidim.io/api/v1/integrations/custom-api" \
  -H "Authorization: Bearer $OMNIDIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Order status",
  "description": "Look up an order'\''s delivery status by order number.",
  "url": "https://api.acme-corp.io/orders/status",
  "method": "GET",
  "headers": [
    {
      "key": "Authorization",
      "value": "Bearer YOUR_TOKEN"
    }
  ],
  "query_params": [
    {
      "key": "order_number",
      "description": "The order number the caller reads out",
      "type": "string",
      "required": true,
      "isLLMGenerated": true
    }
  ]
}'
```