NUACOM API

Calls

Callbacks

A callback is a call NUACOM places for you in two legs: the platform first rings one of the account's extensions or a queue and, once that leg is answered, dials the destination number and bridges the two. In the API it is a single operation, POST /v2/request-callback. The extension and queue numbers it starts from come from the Extensions and Queues groups.

Workflow (what the portal does)

  1. Pick the origin: an extension number from GET /v2/extensions (number) or a queue number from GET /v2/queues (number, not the queue id).
  2. Request the call: POST /v2/request-callback with method (extension or queue), from_number (the extension or queue number, up to 20 characters) and dst_number (the destination in E.164, +353861234567, up to 20 characters). The answer is 200 with {"data": true} when the platform accepted the request and {"data": false} when it refused it.
  3. What happens next: with extension, the extension rings for up to 30 seconds showing the caller ID name WebCall +353861234567 (the destination); when the agent answers, the destination is dialled from that extension and the two legs are bridged. With queue, the call is placed into the queue and offered to its agents under the same WebCall name, and the destination is dialled when an agent answers. If nobody answers within 30 seconds, nothing is dialled.
  4. Afterwards: the request returns nothing beyond data: no call id and no status to poll.
curl -X POST https://api.api-nuacom.com/v2/request-callback \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"method":"extension","from_number":"101","dst_number":"+353861234567"}'
# → {"data":true}

How a callback connects two legs

sequenceDiagram
    participant I as Your integration
    participant API as NUACOM API
    participant Origin as Extension or queue (leg 1)
    participant Dst as Destination number (leg 2)

    I->>API: POST /v2/request-callback<br/>method, from_number, dst_number
    API-->>I: 200 {data: true}
    API->>Origin: Ring for up to 30 seconds<br/>caller ID "WebCall <dst_number>"
    alt answered within 30 seconds
        Origin-->>API: Answered
        API->>Dst: Dial dst_number
        Dst-->>API: Answered
        Note over Origin,Dst: Two legs bridged
    else nobody answers within 30 seconds
        Note over API,Origin: Nothing is dialled
    end

Validation errors

A rejected body answers 422 with the first error as message and every error under errors:

{
  "message": "Extension is not available for input account id.",
  "errors": {
    "from_number": ["Extension is not available for input account id."]
  },
  "trace": null
}
Field Error text When
method The method field is required. Missing
method The selected method is invalid. Not extension or queue
from_number The from number field is required. Missing
from_number Extension is not available for input account id. method is extension and the account has no extension with that number
from_number Queue not available for account. method is queue and the account has no queue with that number
dst_number The dst number field is required. Missing
dst_number dst number has an invalid phone format Cannot be read as a phone number
dst_number The dst number field must not be greater than 20 characters. Longer than 20 characters

Roles and access

  • Any authenticated user; there is no admin gate. The call is placed on the account behind the token, from the extension or queue you name.
  • 500 means the telephony platform could not be reached; {"data": false} means it answered but did not place the call.

Pitfalls

  • dst_number is dialled exactly as you send it. The format check reads it in the user's country, so a national number such as 0861234567 can pass validation for an Irish user, but the platform still receives that string unchanged. Always send E.164.
  • For queue, from_number is the queue number (number in GET /v2/queues), not its id; the API resolves the id itself.
  • A refusal comes back as 200 with {"data": false}, not as an error status. Check the flag.
  • The first leg rings for 30 seconds at most; the limit is not configurable per request.
  • The API does not de-duplicate requests; each one is handed to the platform as a new call.