> ## Documentation Index > Fetch the complete documentation index at: https://docs.sigmamind.ai/llms.txt > Use this file to discover all available pages before exploring further. # Import Phone Number > Imports an existing phone number via SIP trunking (BYO). Provide the number in +E.164 format along with SIP credentials (trunkUsername, trunkPassword, terminationSipURI). Returns the imported number, including its sipPhoneNumber. ## OpenAPI ````yaml post /v1/phone-numbers/import openapi: 3.0.1 info: title: SigmaMind APIs description: OpenAPI documentation SigmaMind Agent Builder APIs version: '1.0' servers: - url: https://api.sigmamind.ai description: SigmaMind AI Agent Builder APIs security: - apiKeyAuth: [] tags: - name: Chats description: >- Endpoints for creating and managing text-based chat sessions with an agent. A session is started by specifying an agent and an opening message. Returns a chatId used in all subsequent get, update, completion, and end-session calls. - name: Calls description: >- Endpoints for creating and managing outbound phone calls. A call is initiated by specifying an agent, caller number, and destination number — dynamic variables can be included to personalise the agent's behaviour. Returns a callId used in all subsequent get and delete operations. - name: Phone Numbers description: >- Endpoints for managing phone numbers used in outbound and inbound calls. Supports purchasing a new number through SigmaMind or importing an existing number via SIP trunking (BYO). Each number can be assigned separate inbound and outbound agents. - name: Campaigns description: >- Endpoints for creating and managing outbound call campaigns. A campaign dials a CSV-uploaded contact list using a selected agent and caller number, with support for immediate or scheduled launch. Returns a campaignId used in all subsequent get, update, and delete operations. - name: Agents description: >- Endpoints for creating and managing single prompt agents. An agent is configured with a system prompt, voice settings, and optional tools. Returns an agentId used in all subsequent update, call, and simulation operations. - name: Integrations description: >- Endpoints for creating and managing third-party integrations (e.g. Shopify, Cal.com). An integration links your account to an external service and acts as the parent resource for auth credentials and API tools. Returns an integrationId used in all subsequent auth and tool operations. - name: Integration Auth description: >- Endpoints for managing authentication credentials for a third-party integration. Supports API Key, Basic, and Bearer token credential types — scoped to an integration and injected automatically by tools when executing. Returns an authId used in all subsequent get, update, and delete operations. - name: Integration Tools description: >- Endpoints for creating and managing API tools backed by a third-party integration. Each tool defines an HTTP endpoint, method, and parameter schema — scoped to an integration and using its stored auth credentials when executing. Returns a toolId used in all subsequent get, update, delete, and execute operations. - name: Webhooks description: >- Endpoints for registering and managing webhooks. A webhook delivers real-time event notifications via HTTP POST when selected events occur on a specific agent — each webhook is scoped to one agent and one or more event types. Payloads are signed with an HMAC secret — verify the signature on your server to confirm authenticity. - name: Test Cases description: >- Endpoints for creating and managing simulation test cases for an agent. A test case defines a conversation scenario — including user persona, goals, and expected behaviour — used to generate a synthetic conversation with the agent. Returns a testCaseId used in all subsequent get, update, delete, and batch-run operations. - name: Batch Runs description: >- Endpoints for creating and managing batch runs of simulation test cases. A batch run executes multiple test cases in parallel against a selected agent and aggregates the results for review. Returns a batchId used in all subsequent get and list test-run operations. - name: Test Runs description: >- Endpoints for retrieving test run results within a batch. Each test run represents a single test case execution within a batch run, identified by a jobId. Use batchId and agentId to scope results to the correct batch. - name: API Keys description: >- Endpoints for creating and managing API keys used to authenticate public API requests. Each key must be included in the X-API-Key request header. Returns a keyId used in all subsequent get, revoke, and delete operations. - name: QA Rules description: >- Endpoints for creating and managing quality assurance rules applied to agent conversations. A QA rule defines evaluation criteria used to automatically assess conversation quality. Returns a qaRuleId used in all subsequent get, update, and delete operations. - name: QA Issues description: >- Endpoints for retrieving and managing quality assurance issues flagged across agent conversations. A QA issue is created with status 'Fail' when a conversation violates one or more QA rules — capturing the offending rule reference. It is created with status 'Success' when the conversation passes the evaluation criteria of QA rule(s). Returns a qaIssueId used in all subsequent get operations. paths: /v1/phone-numbers/import: post: tags: - Phone Numbers summary: Import Phone Number description: >- Imports an existing phone number via SIP trunking (BYO). Provide the number in +E.164 format along with SIP credentials (trunkUsername, trunkPassword, terminationSipURI). Returns the imported number, including its sipPhoneNumber. operationId: importPhoneNumber requestBody: content: application/json: schema: $ref: '#/components/schemas/ImportPhoneNumberRequest_Byo' required: true responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/PhoneNumberResponse_Byo' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/phone-numbers status: 400 timestamp: '2026-05-05T10:06:45.720Z' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/phone-numbers status: 401 timestamp: '2026-05-05T10:06:45.720Z' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/phone-numbers status: 403 timestamp: '2026-05-05T10:06:45.720Z' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/phone-numbers status: 404 timestamp: '2026-05-05T10:06:45.720Z' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/phone-numbers status: 500 timestamp: '2026-05-05T10:06:45.720Z' components: schemas: ImportPhoneNumberRequest_Byo: type: object properties: friendlyName: maxLength: 128 minLength: 0 type: string description: >- Human-readable label for this phone number. Used to identify it in listings and dashboards. If omitted, the number itself is used as the display name. example: BYO - Main Office Line phoneNumber: pattern: ^\+[1-9][0-9]{6,14}$ type: string description: >- The phone number being imported, in +E.164 format (e.g., +14155552671). Must be a number you own and have configured on your external SIP trunk. This number will be registered in SigmaMind and used as the caller ID for outbound calls and the destination for inbound calls routed through your trunk. example: '+14155552671' inboundAgentId: maxLength: 64 minLength: 0 type: string description: >- Unique identifier of the agent that will handle inbound calls received on this number. When a call arrives at this number via the SIP trunk, it is routed to this agent automatically. If omitted, inbound calls will not be handled by an agent until one is assigned. example: awTw7UKhOsLGiDbt outboundAgentId: maxLength: 64 minLength: 0 type: string description: >- Unique identifier of the agent that will handle outbound calls made from this number. When this number is used as the caller ID in an outbound call, this agent manages the conversation. If omitted, the agent must be specified explicitly at call creation time. example: awTw7UKhOsLGiDbt trunkUsername: maxLength: 128 minLength: 0 type: string description: >- Username credential for authenticating outbound calls on your SIP trunk. Must match the trunk username configured in your telecom provider's account. Required for outbound call routing through the trunk. example: my_trunk_user trunkPassword: maxLength: 128 minLength: 0 type: string description: >- Password credential for authenticating outbound calls on your SIP trunk. Must match the trunk password configured in your telecom provider's account. Required for outbound call routing through the trunk. Stored securely and never returned in API responses. example: tr!nkP@ssword terminationSipURI: maxLength: 253 minLength: 0 type: string description: >- SIP URI of the termination endpoint provided by your telecom provider. SigmaMind sends outbound calls to this address to route them through your trunk. Obtain this value from your provider's SIP trunking configuration (e.g., 'sip.telnyx.com', 'sip.twilio.com'). Required for outbound call delivery. example: sip.telnyx.com outboundPhoneNumber: pattern: ^\+[1-9][0-9]{6,14}$ type: string description: >- Default destination number dialled during test calls initiated from this phone number, in +E.164 format. Used to verify the SIP trunk is connected and routing calls correctly. Must be a valid number capable of receiving calls. If omitted, test calls cannot be placed until this is configured. example: '+14155552671' description: >- Request body to import an existing phone number you own into SigmaMind via SIP trunking (BYO — Bring Your Own number). Use this when the number is already provisioned with an external telecom provider and you want SigmaMind to route calls through it using your own SIP trunk credentials. The number is not purchased — it remains with your provider. PhoneNumberResponse_Byo: type: object properties: sipPhoneNumber: type: string description: >- The caller’s phone number in +E.164 format. This number must be obtained from SigmaMind or configured using SIP trunking with SigmaMind. example: '+14155552671' inboundAgentId: type: string description: >- Default agent ID assigned to handle inbound calls for this phone number. example: D5D0p7TUs66TTAEAx outboundAgentId: type: string description: >- Default agent ID assigned to handle outbound calls for this phone number. example: D5D0p7TUs66TTAEAx outboundPhoneNumber: type: string description: >- The default outbound phone number of the callee, represented in +E.164 format example: '+14155552671' active: type: boolean description: >- Indicates whether the phone number is currently active and available for use. example: true terminationSipURI: type: string description: >- The SIP URI of the phone number, provided by the service provider for call termination. example: sip.telnyx.com friendlyName: type: string description: A user-friendly display name assigned to this phone number. example: Support Line - US Error: type: object properties: timestamp: type: string description: Error timestamp in ISO format format: date-time status: type: integer description: HTTP status code example: 400 error: type: string description: Error type or HTTP status message example: Bad Request message: type: string description: Detailed error message example: Email is required path: type: string description: Request path where error occurred example: /v1/users validationErrors: type: object description: Field validation errors (if any) example: |- { "email": "Email is required", "name": "Name is too short" } description: Standard error response securitySchemes: apiKeyAuth: type: apiKey description: >- Authenticate every request by passing your API key in the `X-API-Key` header. To get your key, go to Dashboard → API Keys and create or copy your Production API key. name: X-API-Key in: header ````