User API

The Calldrip User API allows external systems to programmatically manage users within a Calldrip organization. You can create, update, retrieve, and delete users, as well as look up users by email address or phone number. All endpoints communicate over HTTPS and return JSON responses.

{primary} The User API accepts JSON requests and returns JSON responses for all endpoints.

Because the REST API is based on open standards, you can use any web development language to access the API.

{warning} Prerequisites — read before getting started

Two things must be in place before the API can be used:

API credentials: A API key (apiuser / apikey) must be issued for your organization. Contact support to have this configured.

Organization and accounts: The organizationId and accountIds you reference must exist in Calldrip and be associated with your API credentials.

Contact support@calldrip.com (US) or support@dcdw.nl (EU) to have these set up.

Getting Started

Contact support to receive your API credentials (apiuser and apikey).
Pass credentials as request headers on every call.
Send a test request against the API to create or retrieve a user.
Contact support when you receive a success response to verify the integration.

API Endpoint

Base URL: https://app.calldrip.com/api/users

All endpoints accept Content-Type: application/json requests. Responses are always application/json.

Authentication

All requests must include your API credentials as HTTP request headers:

Header	Description
`apiuser`	Your API username, issued by support
`apikey`	Your API key, issued by support

{warning} Important! Keep your API key safe. Never expose it in client-side code or public repositories.

If your credentials are missing or invalid the API returns:

{"success": false, "message": "Invalid API key"}

If your credentials do not have access to the requested organization the API returns:

{"success": false, "message": "Unauthorized for this organization"}

Endpoints Overview

Method	Path	Action
`POST`	`/api/users`	Create a new user
`PUT`	`/api/users/{user}`	Update an existing user
`GET`	`/api/users/{user}`	Retrieve a user by ID
`DELETE`	`/api/users/{user}`	Delete a user
`GET`	`/api/users/find/email`	Find a user by email address
`GET`	`/api/users/find/phone`	Find a user by phone number
`GET`	`/api/users/find/available-user-code`	Get the next available user code

Create User

POST /api/users

Creates a new user within the specified organization and assigns them to one or more accounts.

Request Body

Field	Required	Description
`organizationId`	Yes	ID of the organization to create the user in
`firstName`	Yes	User's first name (max 45 characters)
`lastName`	Yes	User's last name (max 45 characters)
`emailAddress`	Yes	User's email address (max 255 characters)
`accountIds`	Yes	Array of account IDs to assign the user to (must belong to the organization)
`username`	No	Unique username (max 75 characters). Defaults to `emailAddress` if omitted
`password`	No	Password (min 7, max 255 characters). Must contain at least one digit, one lowercase, one uppercase and one special character
`phoneNumber`	No	Phone number in E.164 format, e.g. `+31628866642`
`companyRole`	No	User's role within the company (max 255 characters)
`permissionTemplate`	No	Name of an existing permission template (e.g. `Agent`, `Manager`, `Global Manager`). Defaults to `Agent`
`profilePicture`	No	HTTPS URL to an image that will be downloaded and stored
`timezone`	No	Timezone code (e.g. `Europe/Amsterdam`). Defaults to the account timezone
`country`	No	Country name (e.g. `Netherlands`). Defaults to the account country
`bio`	No	Short biography (max 255 characters)
`code`	No	Numeric user code. Must be unique within the organization. Auto-assigned if omitted
`twelveHourTimeFormat`	No	`true` to use 12-hour clock display, `false` for 24-hour (default)
`teams`	No	Array of team IDs to assign the user to. Defaults to all teams in the assigned accounts
`schedule`	No	Availability schedule object (see schedule structure below)

Schedule Object Structure

When providing a schedule, all fields below are required within it:

{
  "schedule": {
    "active": true,
    "monday":    { "active": true,  "startTime": "09:00", "endTime": "17:00" },
    "tuesday":   { "active": true,  "startTime": "09:00", "endTime": "17:00" },
    "wednesday": { "active": true,  "startTime": "09:00", "endTime": "17:00" },
    "thursday":  { "active": true,  "startTime": "09:00", "endTime": "17:00" },
    "friday":    { "active": true,  "startTime": "09:00", "endTime": "17:00" },
    "saturday":  { "active": false, "startTime": "09:00", "endTime": "17:00" },
    "sunday":    { "active": false, "startTime": "09:00", "endTime": "17:00" }
  }
}

Times must be in HH:MM (24-hour) format. endTime must be after startTime for each day.

Example Request

{
  "organizationId": 1,
  "firstName": "Jane",
  "lastName": "Doe",
  "emailAddress": "jane.doe@example.com",
  "accountIds": [10, 11],
  "phoneNumber": "+31628866642",
  "permissionTemplate": "Agent",
  "timezone": "Europe/Amsterdam",
  "country": "Netherlands",
  "code": "05",
  "twelveHourTimeFormat": false,
  "teams": [3, 7],
  "schedule": {
    "active": true,
    "monday":    { "active": true,  "startTime": "08:00", "endTime": "17:00" },
    "tuesday":   { "active": true,  "startTime": "08:00", "endTime": "17:00" },
    "wednesday": { "active": true,  "startTime": "08:00", "endTime": "17:00" },
    "thursday":  { "active": true,  "startTime": "08:00", "endTime": "17:00" },
    "friday":    { "active": true,  "startTime": "08:00", "endTime": "16:00" },
    "saturday":  { "active": false, "startTime": "09:00", "endTime": "17:00" },
    "sunday":    { "active": false, "startTime": "09:00", "endTime": "17:00" }
  }
}

Success Response (HTTP 201)

{
  "success": true,
  "action": "create_user",
  "message": "User created successfully",
  "user": {
    "id": 42,
    "firstName": "Jane",
    "lastName": "Doe",
    "fullName": "Jane Doe",
    "emailAddress": "jane.doe@example.com",
    "username": "jane.doe@example.com",
    "phoneNumber": "+31628866642",
    "companyRole": null,
    "imageUrl": null,
    "timezone": "Europe/Amsterdam",
    "country": "Netherlands",
    "bio": null,
    "code": "05",
    "twelveHourTimeFormat": false,
    "organizationIds": [1],
    "accountIds": [10, 11],
    "teams": [
      { "id": 3, "name": "Sales", "accountId": 10 }
    ],
    "schedule": {
      "active": true,
      "monday":    { "active": true,  "startTime": "08:00", "endTime": "17:00" },
      "tuesday":   { "active": true,  "startTime": "08:00", "endTime": "17:00" },
      "wednesday": { "active": true,  "startTime": "08:00", "endTime": "17:00" },
      "thursday":  { "active": true,  "startTime": "08:00", "endTime": "17:00" },
      "friday":    { "active": true,  "startTime": "08:00", "endTime": "16:00" },
      "saturday":  { "active": false, "startTime": "09:00", "endTime": "17:00" },
      "sunday":    { "active": false, "startTime": "09:00", "endTime": "17:00" }
    }
  }
}

Update User

PUT /api/users/{user}

Updates an existing user. Only the fields you include in the request body are changed; all omitted fields retain their current values.

Path Parameters

Parameter	Description
`{user}`	The Calldrip user ID

Request Body

All fields are optional. Include only the fields you want to update.

Field	Description
`organizationId`	Organization context for validation (uses the user's current organization if omitted)
`firstName`	Updated first name
`lastName`	Updated last name
`emailAddress`	Updated email address
`username`	Updated username (must be globally unique)
`password`	Updated password (same complexity requirements as create)
`phoneNumber`	Updated phone number in E.164 format
`companyRole`	Updated company role
`permissionTemplate`	Name of a permission template to apply
`profilePicture`	HTTPS URL to a new profile image
`bio`	Updated biography
`code`	Updated user code (must be unique within the organization)
`twelveHourTimeFormat`	`true` or `false`
`accountIds`	Replaces the full list of assigned accounts
`teams`	Replaces the full list of assigned teams. Pass an empty array `[]` to remove all teams
`schedule`	Replaces the full schedule (same structure as create)

Success Response (HTTP 200)

{
  "success": true,
  "action": "update_user",
  "message": "User updated successfully",
  "user": { }
}

The user object has the same shape as the create response.

Get User

GET /api/users/{user}

Retrieves a single user by their Calldrip user ID.

Path Parameters

Parameter	Description
`{user}`	The Calldrip user ID

Success Response (HTTP 200)

{
  "success": true,
  "action": "get_user",
  "message": "User retrieved successfully",
  "user": { }
}

The user object has the same shape as the create response.

Delete User

DELETE /api/users/{user}

Permanently deletes a user and their associated schedule. The user's profile image is also removed from storage.

Path Parameters

Parameter	Description
`{user}`	The Calldrip user ID

Success Response (HTTP 200)

{
  "success": true,
  "action": "delete_user",
  "message": "User deleted successfully"
}

{warning} Deletion is permanent and cannot be undone. Ensure you have retrieved or backed up any data you need before deleting.

Find User by Email

GET /api/users/find/email

Looks up a user within a specific organization by their email address.

Query Parameters

Parameter	Required	Description
`organizationId`	Yes	The organization to search in
`emailAddress`	Yes	The email address to search for

Example Request

GET /api/users/find/email?organizationId=1&emailAddress=jane.doe@example.com

Success Response (HTTP 200)

{
  "success": true,
  "action": "get_user_by_email_address",
  "message": "User retrieved successfully",
  "user": { }
}

Returns a 404 with {"success": false, "message": "User not found"} when no match is found.

Find User by Phone

GET /api/users/find/phone

Looks up a user within a specific organization by their phone number.

Query Parameters

Parameter	Required	Description
`organizationId`	Yes	The organization to search in
`phoneNumber`	Yes	Full phone number in E.164 format, e.g. `+31628866642`

Example Request

GET /api/users/find/phone?organizationId=1&phoneNumber=%2B31628866642

Success Response (HTTP 200)

{
  "success": true,
  "action": "get_user_by_phone_number",
  "message": "User retrieved successfully",
  "user": { }
}

Returns a 404 with {"success": false, "message": "User not found"} when no match is found.

Get Available User Code

GET /api/users/find/available-user-code

Returns the next available numeric user code within the specified organization. Useful when you want to pre-fill a code before creating a user.

Query Parameters

Parameter	Required	Description
`organizationId`	Yes	The organization to check codes for

Example Request

GET /api/users/find/available-user-code?organizationId=1

Success Response (HTTP 200)

{
  "success": true,
  "action": "get_available_user_code",
  "message": "Next available user code retrieved successfully",
  "code": "06"
}

Response Format

All responses share a common JSON envelope:

Field	Type	Description
`success`	boolean	`true` on success, `false` on failure
`action`	string	Machine-readable identifier for the operation performed
`message`	string	Human-readable description of the result
`user`	object	Present on create, update, and retrieval responses
`code`	string	Present on the available-user-code response

User Object Fields

Field	Type	Description
`id`	integer	Calldrip user ID
`firstName`	string	First name
`lastName`	string	Last name
`fullName`	string	Concatenated full name
`emailAddress`	string	Email address
`username`	string	Login username
`phoneNumber`	string	Phone number in E.164 format
`companyRole`	string\|null	Role within the company
`imageUrl`	string\|null	Public URL of the profile picture
`timezone`	string	Timezone code
`country`	string	Country name
`bio`	string\|null	Short biography
`code`	string\|null	Numeric user code as a zero-padded string
`twelveHourTimeFormat`	boolean	Whether to display times in 12-hour format
`organizationIds`	array	IDs of organizations the user belongs to
`accountIds`	array	IDs of accounts the user is assigned to
`teams`	array	Teams the user is a member of (`id`, `name`, `accountId`)
`schedule`	object\|null	Availability schedule

Error Responses

{"success": false, "message": "User not found"}

{"success": false, "message": "Invalid API key"}

{
  "message": "The given data was invalid.",
  "errors": {
    "emailAddress": ["The email address field is required."],
    "accountIds": ["The account ids field is required."]
  }
}

Example Using cURL

Create User

curl -X POST "https://app.calldrip.com/api/users" \
  -H "Content-Type: application/json" \
  -H "apiuser: your_api_username" \
  -H "apikey: your_api_key" \
  -d '{
    "organizationId": 1,
    "firstName": "Jane",
    "lastName": "Doe",
    "emailAddress": "jane.doe@example.com",
    "accountIds": [10]
  }'

Update User

curl -X PUT "https://app.calldrip.com/api/users/42" \
  -H "Content-Type: application/json" \
  -H "apiuser: your_api_username" \
  -H "apikey: your_api_key" \
  -d '{
    "firstName": "Jane",
    "companyRole": "Sales Manager"
  }'

Get User

curl -X GET "https://app.calldrip.com/api/users/42" \
  -H "apiuser: your_api_username" \
  -H "apikey: your_api_key"

Delete User

curl -X DELETE "https://app.calldrip.com/api/users/42" \
  -H "apiuser: your_api_username" \
  -H "apikey: your_api_key"

Find by Email

curl -X GET "https://app.calldrip.com/api/users/find/email?organizationId=1&emailAddress=jane.doe%40example.com" \
  -H "apiuser: your_api_username" \
  -H "apikey: your_api_key"

Find by Phone

curl -X GET "https://app.calldrip.com/api/users/find/phone?organizationId=1&phoneNumber=%2B31628866642" \
  -H "apiuser: your_api_username" \
  -H "apikey: your_api_key"

Get Available User Code

curl -X GET "https://app.calldrip.com/api/users/find/available-user-code?organizationId=1" \
  -H "apiuser: your_api_username" \
  -H "apikey: your_api_key"

Best Practices

User Creation

Always specify accountIds for all accounts the user should be active in
Supply a permissionTemplate that matches the user's intended role; defaulting to Agent is safe
Use getAvailableUserCode before creating to avoid code conflicts when you need a predictable code
Provide timezone and country explicitly rather than relying on account defaults when users are in a different region

Data Quality

Send phone numbers in E.164 format (e.g. +31628866642) to avoid validation failures
Use consistent email address casing — email addresses are matched case-sensitively as usernames
Provide a schedule if the user has non-default working hours; otherwise the account schedule is copied

Security

Store API credentials securely — never hard-code them in source code
Use HTTPS for all API calls
Rotate API keys periodically and contact support if a key is compromised

Testing

Request test credentials from support
Use a dedicated test organization and test accounts to isolate test data from production
Test all operations: create, update, get, delete, and both lookup endpoints
Verify the user object in responses matches what you sent

Get Started

Receiving Lead Data

Sending Call Data

Fetching Call Data

Other

User API

Getting Started

API Endpoint

Authentication

Endpoints Overview

Create User

Request Body

Schedule Object Structure

Example Request

Success Response (HTTP 201)

Update User

Path Parameters

Request Body

Success Response (HTTP 200)

Get User

Path Parameters

Success Response (HTTP 200)

Delete User

Path Parameters

Success Response (HTTP 200)

Find User by Email

Query Parameters

Example Request

Success Response (HTTP 200)

Find User by Phone

Query Parameters

Example Request

Success Response (HTTP 200)

Get Available User Code

Query Parameters

Example Request

Success Response (HTTP 200)

Response Format

User Object Fields

Error Responses

Example Using cURL

Create User

Update User

Get User

Delete User

Find by Email

Find by Phone

Get Available User Code

Best Practices

User Creation

Data Quality

Security

Testing