SIP

Your SIP trunk configuration.

List SIP configurations

GET /sip-config/organisation/{organisationId}

Lists every SIP configuration (inbound and outbound, active and inactive) in your organisation, oldest first, with the customer-facing rental and surcharge prices. Internal carrier costs are never included.

Scope: sip:read

Parameters

Name	In	Type	Required	Description
`organisationId`	path	string	yes	Your organisation ID. Must be the API key’s own organisation, otherwise 403.

Example request

curl -X GET "https://api.foan.ai/api/v1/sip-config/organisation/{organisationId}" \
  -H "Authorization: Bearer $FOAN_API_KEY"

Response 200

{
  "success": true,
  "data": [
    {
      "id": "cmf3k2j9x0007abcd1234efgh",
      "organisationId": "cmf3k2j9x0001abcd1234efgh",
      "sipTrunkId": "ST_a1B2c3D4e5F6",
      "type": "INBOUND",
      "providerId": "cmf3k2j9x0008abcd1234efgh",
      "provider": {
        "id": "cmf3k2j9x0008abcd1234efgh",
        "name": "TATATELE",
        "displayName": "Tata Tele",
        "isSystem": false,
        "isActive": true,
        "createdAt": "2026-01-05T06:00:00.000Z",
        "updatedAt": "2026-01-05T06:00:00.000Z"
      },
      "agentId": "cmf3k2j9x0003abcd1234efgh",
      "phoneNumber": "+918041234567",
      "maxConcurrentCalls": 5,
      "maxQueueSize": 10,
      "callTimeoutMs": 30000,
      "callingScope": "SAME_COUNTRY",
      "allowedCountries": [],
      "sipReferEnabled": false,
      "customerRentalPerMonth": 500,
      "customerInboundSurchargePerMin": 0,
      "customerOutboundSurchargePerMin": 0,
      "isActive": true,
      "createdAt": "2026-09-20T10:15:00.000Z",
      "updatedAt": "2026-09-24T08:30:00.000Z"
    }
  ],
  "message": "SIP configurations retrieved successfully"
}

Errors

Code	When
400	Validation failed (the error message lists the failing fields).
401	Missing, invalid or revoked API key, or the key owner no longer belongs to the organisation.
403	The key lacks the required scope, or organisationId is not the key’s own organisation.
429	Rate limited
500	Unexpected failure reading configurations.

Get a SIP configuration

GET /sip-config/{id}

Returns one SIP configuration by ID. The configuration must belong to your organisation (403 otherwise).

Scope: sip:read

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes	SIP configuration ID.

Example request

curl -X GET "https://api.foan.ai/api/v1/sip-config/{id}" \
  -H "Authorization: Bearer $FOAN_API_KEY"

Response 200

{
  "success": true,
  "data": {
    "id": "cmf3k2j9x0007abcd1234efgh",
    "organisationId": "cmf3k2j9x0001abcd1234efgh",
    "sipTrunkId": "ST_a1B2c3D4e5F6",
    "type": "INBOUND",
    "providerId": "cmf3k2j9x0008abcd1234efgh",
    "provider": {
      "id": "cmf3k2j9x0008abcd1234efgh",
      "name": "TATATELE",
      "displayName": "Tata Tele",
      "isSystem": false,
      "isActive": true,
      "createdAt": "2026-01-05T06:00:00.000Z",
      "updatedAt": "2026-01-05T06:00:00.000Z"
    },
    "agentId": "cmf3k2j9x0003abcd1234efgh",
    "phoneNumber": "+918041234567",
    "maxConcurrentCalls": 5,
    "maxQueueSize": 10,
    "callTimeoutMs": 30000,
    "callingScope": "SAME_COUNTRY",
    "allowedCountries": [],
    "sipReferEnabled": false,
    "customerRentalPerMonth": 500,
    "customerInboundSurchargePerMin": 0,
    "customerOutboundSurchargePerMin": 0,
    "isActive": true,
    "createdAt": "2026-09-20T10:15:00.000Z",
    "updatedAt": "2026-09-24T08:30:00.000Z"
  },
  "message": "SIP configuration retrieved successfully"
}

Errors

Code	When
401	Missing, invalid or revoked API key, or the key owner no longer belongs to the organisation.
403	The key lacks sip:read, or the configuration belongs to another organisation.
404	SIP configuration not found.
429	Rate limited

List inbound SIP configurations

GET /sip-config/organisation/{organisationId}/inbound

Lists only the INBOUND SIP configurations in your organisation (the numbers an agent can answer). Includes both assigned and unassigned ones, and inactive ones too.

Scope: sip:read

Parameters

Name	In	Type	Required	Description
`organisationId`	path	string	yes	Your organisation ID. Must be the API key’s own organisation, otherwise 403.

Example request

curl -X GET "https://api.foan.ai/api/v1/sip-config/organisation/{organisationId}/inbound" \
  -H "Authorization: Bearer $FOAN_API_KEY"

Response 200

{
  "success": true,
  "data": [
    {
      "id": "cmf3k2j9x0007abcd1234efgh",
      "organisationId": "cmf3k2j9x0001abcd1234efgh",
      "sipTrunkId": "ST_a1B2c3D4e5F6",
      "type": "INBOUND",
      "providerId": "cmf3k2j9x0008abcd1234efgh",
      "provider": {
        "id": "cmf3k2j9x0008abcd1234efgh",
        "name": "TATATELE",
        "displayName": "Tata Tele",
        "isSystem": false,
        "isActive": true,
        "createdAt": "2026-01-05T06:00:00.000Z",
        "updatedAt": "2026-01-05T06:00:00.000Z"
      },
      "agentId": "cmf3k2j9x0003abcd1234efgh",
      "phoneNumber": "+918041234567",
      "maxConcurrentCalls": 5,
      "maxQueueSize": 10,
      "callTimeoutMs": 30000,
      "callingScope": "SAME_COUNTRY",
      "allowedCountries": [],
      "sipReferEnabled": false,
      "customerRentalPerMonth": 500,
      "customerInboundSurchargePerMin": 0,
      "customerOutboundSurchargePerMin": 0,
      "isActive": true,
      "createdAt": "2026-09-20T10:15:00.000Z",
      "updatedAt": "2026-09-24T08:30:00.000Z"
    }
  ],
  "message": "Available INBOUND SIP configurations retrieved successfully"
}

Errors

Code	When
400	Validation failed (the error message lists the failing fields).
401	Missing, invalid or revoked API key, or the key owner no longer belongs to the organisation.
403	The key lacks the required scope, or organisationId is not the key’s own organisation.
429	Rate limited
500	Unexpected failure reading configurations.