JustCall User Management API Guide

Auth method: API Key + Secret (HTTP Basic-style header: Authorization: Basic base64(api_key:api_secret))

Setup steps

1. Log in to JustCall dashboard and navigate to Settings > Developer > API.
2. Click 'Generate API Key' to create an API Key and API Secret pair.
3. Base64-encode the string 'api_key:api_secret'.
4. Include the encoded value in the Authorization header as: Authorization: Basic .
5. Optionally whitelist IP addresses in the API settings for additional security.

List Agents

• Method: GET
• URL: https://api.justcall.io/v1/agents
• Watch out for: Returns all agents including inactive ones; filter by status client-side if needed.

Request example

GET /v1/agents?page=1&per_page=25
Authorization: Basic <base64_key_secret>

Response example

{
  "status": "success",
  "data": [
    {"id":101,"firstname":"Jane","lastname":"Doe","email":"jane@example.com","role":"agent"}
  ],
  "total": 50,
  "page": 1
}

Get Agent

• Method: GET
• URL: https://api.justcall.io/v1/agents/{agent_id}
• Watch out for: Returns 404 if agent_id does not belong to the authenticated account.

Request example

GET /v1/agents/101
Authorization: Basic <base64_key_secret>

Response example

{
  "status": "success",
  "data": {
    "id":101,"firstname":"Jane","lastname":"Doe",
    "email":"jane@example.com","timezone":"America/New_York"
  }
}

Create Agent (Invite User)

• Method: POST
• URL: https://api.justcall.io/v1/agents
• Watch out for: Creates the agent and sends an invitation email. The agent must accept the invite to activate the account. Duplicate email returns an error.

Request example

POST /v1/agents
Content-Type: application/json

{"firstname":"John","lastname":"Smith","email":"john@example.com","role":"agent"}

Response example

{
  "status": "success",
  "data": {
    "id":202,"firstname":"John","lastname":"Smith",
    "email":"john@example.com"
  }
}

Update Agent

• Method: POST
• URL: https://api.justcall.io/v1/agents/{agent_id}
• Watch out for: JustCall uses POST (not PATCH/PUT) for updates on this endpoint. Only include fields to be changed.

Request example

POST /v1/agents/202
Content-Type: application/json

{"firstname":"Jonathan","timezone":"Europe/London"}

Response example

{
  "status": "success",
  "data": {
    "id":202,"firstname":"Jonathan","timezone":"Europe/London"
  }
}

Delete / Deactivate Agent

• Method: DELETE
• URL: https://api.justcall.io/v1/agents/{agent_id}
• Watch out for: Deletion is permanent and removes the agent from the account. Call recordings and logs associated with the agent are retained per account data-retention settings.

Request example

DELETE /v1/agents/202
Authorization: Basic <base64_key_secret>

Response example

{
  "status": "success",
  "message": "Agent deleted successfully"
}

List Teams

• Method: GET
• URL: https://api.justcall.io/v1/teams
• Watch out for: Team membership is returned as an array of agent IDs; resolve agent details with separate GET /agents/{id} calls.

Request example

GET /v1/teams?page=1&per_page=25
Authorization: Basic <base64_key_secret>

Response example

{
  "status": "success",
  "data": [
    {"id":10,"name":"Support Team","agents":[101,202]}
  ]
}

Add Agent to Team

• Method: POST
• URL: https://api.justcall.io/v1/teams/{team_id}/agents
• Watch out for: Agent must already exist in the account before being added to a team.

Request example

POST /v1/teams/10/agents
Content-Type: application/json

{"agent_id":202}

Response example

{
  "status": "success",
  "message": "Agent added to team"
}

List Phone Numbers

• Method: GET
• URL: https://api.justcall.io/v1/phone-numbers
• Watch out for: Number assignment to agents is managed here; use the number ID to reassign via a separate update call.

Request example

GET /v1/phone-numbers?page=1&per_page=25
Authorization: Basic <base64_key_secret>

Response example

{
  "status": "success",
  "data": [
    {"id":5,"number":"+14155550100","assigned_to":101,"type":"local"}
  ]
}

• Rate limits: JustCall enforces rate limits per API key. The documented limit is 100 requests per minute per API key. Exceeding the limit returns HTTP 429.
• Rate-limit headers: Yes
• Retry-After header: Yes
• Rate-limit notes: HTTP 429 is returned when the limit is exceeded. Retry-After header indicates when requests can resume. Exact header names (X-RateLimit-Limit, X-RateLimit-Remaining) are referenced in the developer docs but full header spec is not exhaustively published.
• Pagination method: offset
• Default page size: 10
• Max page size: 100
• Pagination pointer: page (1-based) and per_page

• Webhooks available: Yes
• Webhook notes: JustCall supports outbound webhooks configured in the dashboard under Settings > Developer > Webhooks. Webhooks fire on call and SMS events; user/agent lifecycle events (create, delete) are not explicitly documented as webhook triggers.
• Alternative event strategy: Poll GET /v1/agents on a schedule to detect user changes, as agent lifecycle webhooks are not confirmed in official docs.
• Webhook events: call.initiated, call.ringing, call.answered, call.completed, call.missed, sms.received, sms.sent, voicemail.received

• SCIM available: No
• SCIM version: Not documented
• Plan required: Business
• Endpoint: Not documented

Limitations:

• No SCIM provisioning is documented in JustCall's official developer or help center documentation as of the policy date.
• SAML SSO is available on the Business (custom pricing) plan via Okta, Microsoft Entra ID, and OneLogin, but automated SCIM provisioning/deprovisioning is not supported.
• User provisioning must be performed via the REST API or manually through the dashboard.

Provision a new agent by posting firstname, lastname, email, and role to POST /v1/agents. The API immediately sends an invitation email - there is no silent provisioning option.

Capture the returned agent_id, then call POST /v1/teams/{team_id}/agents to assign team membership. Phone number assignment is a separate step via GET /v1/phone-numbers followed by a number-update call; the agent cannot make or receive calls until they accept the invitation regardless of API state.

Deprovision a departing agent by first calling GET /v1/phone-numbers?assigned_to={agent_id} to identify assigned numbers, reassigning them before deletion, then issuing DELETE /v1/agents/{agent_id}. Deletion via API is permanent and irreversible - there is no soft-delete or deactivation-only endpoint documented.

For HR-driven roster sync, paginate GET /v1/agents?per_page=100&page=1 through all pages, diff against the HR system by email, create missing agents, and delete terminated ones. Implement exponential backoff on HTTP 429. Because no SCIM and no agent lifecycle webhooks exist, this sync loop must be built and maintained as a custom integration with no platform-native trigger mechanism.

Provision a new agent and assign to a team

1. POST /v1/agents with firstname, lastname, email, role to create the agent (invitation email sent automatically).
2. Capture the returned agent id from the response.
3. GET /v1/teams to find the target team_id.
4. POST /v1/teams/{team_id}/agents with {agent_id: } to add the agent to the team.
5. Optionally GET /v1/phone-numbers to find an unassigned number and assign it to the agent.

Watch out for: The agent cannot make or receive calls until they accept the invitation email and complete account setup, regardless of API provisioning state.

Deprovision a departing agent

1. GET /v1/agents to locate the agent's id by email.
2. GET /v1/phone-numbers?assigned_to={agent_id} to identify numbers assigned to the agent.
3. Reassign or release those numbers via the phone-numbers update endpoint before deletion.
4. DELETE /v1/agents/{agent_id} to remove the agent from the account.

Watch out for: Deletion is permanent. Confirm number reassignment before deleting to avoid losing access to active phone numbers.

Sync agent roster from an external HR system

1. GET /v1/agents?per_page=100&page=1 (paginate through all pages) to retrieve the current agent list.
2. Compare against the HR system's active employee list by email.
3. For new employees not in JustCall: POST /v1/agents to create them.
4. For terminated employees still in JustCall: DELETE /v1/agents/{agent_id} to remove them.
5. Implement exponential backoff on HTTP 429 responses to respect the 100 req/min rate limit.

Watch out for: No SCIM support means this sync must be built and maintained as a custom integration. There are no agent lifecycle webhooks to trigger real-time deprovisioning.

The most significant API caveat is the update verb: JustCall uses POST to /v1/agents/{agent_id} for updates, not PATCH or PUT. Clients that assume standard REST conventions will silently fail or hit unexpected behavior.

DELETE /v1/agents/{agent_id} is destructive and permanent - there is no deactivation-only API path, which means any automation that calls delete must have number-reassignment logic upstream or risk losing access to active numbers.

API keys carry no scope restrictions, so a compromised key has full account-level access. IP whitelisting is available in the API settings and should be treated as a required control, not optional.

A v2 API is referenced in community posts but is not fully documented for user management as of the policy date; build against v1 only.

For teams using an identity graph to maintain a canonical view of user access across systems, the absence of SCIM and agent lifecycle webhooks means JustCall will always be a polling-dependent node. Plan for eventual consistency rather than real-time state accuracy.