API:Calls:ByID

API » Get Calls By ID Range

Base URL

https://app.callproof.com

Endpoint

/api/calls/by_id/

Purpose

Retrieves call records within a specified call ID range for your CallProof company. Supports pagination so large volumes of call history can be synced in batches by identifier rather than by date. Typically used to keep external systems in sync when advancing through call records sequentially by ID.

HTTP Method

GET

Headers

No required headers.

Header	Required	Description
—	—	No headers are required for this endpoint. Authentication is provided via query parameters.

Security

• Yes – Requires a valid API key and secret with permission to read calls.

Parameters

Query Parameters

Parameter	Type	Required	Description
key	string	Yes	Public API key assigned to your CallProof account.
secret	string	Yes	Private API secret paired with the API key.
after	integer	Yes	Return only calls with an ID greater than or equal to this value. Invalid or missing values cause a validation error.
before	integer	No	Return only calls with an ID less than or equal to this value. If omitted, no upper ID limit is applied.
offset	integer	No	Starting position for paginated results. Defaults to 0 if omitted or invalid.

Path Parameters

None.

Request Body

None.

cURL Example

curl -X GET "https://app.callproof.com/api/calls/by_id/?key=YOUR_API_KEY&secret=YOUR_API_SECRET&after=5000"

Successful Response (200)

Returns a paginated list of calls within the requested ID range. Up to 100 calls are returned per request. If more matching calls exist, more is set to 1 so the caller can request the next page using offset.

Field	Type	Description
results	array	List of call objects (maximum 100 per response).
results[].id	integer	Unique identifier for the call.
results[].created	string	Date and time the call started (YYYY-MM-DD HH:MM:SS).
results[].contact_id	integer	Associated contact identifier.
results[].contact	string	Contact display name.
results[].contact_phone_id	integer	Associated contact phone identifier.
results[].contact_phone	string	Contact phone number used for the call.
results[].user_phone_id	integer	Identifier of the user phone used for the call.
results[].user_phone	string	User phone number used for the call.
results[].phone_number	string	Phone number recorded for the call.
results[].rep	object	Sales representative associated with the call.
results[].rep.id	integer	Rep profile identifier.
results[].rep.email	string	Rep email address.
results[].rep.user_id	integer	Associated user account identifier.
results[].rep.name	string	Rep display name.
results[].rep.title	string	Rep job title.
results[].rep.updated	string	Date and time the rep profile was last updated.
results[].call_type	string	Call type name (for example, incoming or outgoing).
results[].duration	integer	Call duration in seconds.
more	integer	1 if additional matching calls remain; 0 if this is the last page.
offset	integer	Offset value used for this request.
errors	array	Empty list when the request succeeds.
code	integer	HTTP-style status value; 200 on success.

Example response:

{
  "results": [
    {
      "id": 5001,
      "created": "2024-06-15 14:30:00",
      "contact_id": 789,
      "contact": "John Doe",
      "contact_phone_id": 1001,
      "contact_phone": "5551234567",
      "user_phone_id": 22,
      "user_phone": "5559876543",
      "phone_number": "5551234567",
      "rep": {
        "id": 123,
        "email": "rep@example.com",
        "user_id": 456,
        "name": "Jane Smith",
        "title": "Account Executive",
        "updated": "2024-06-01 10:00:00"
      },
      "call_type": "outgoing",
      "duration": 185
    }
  ],
  "more": 0,
  "offset": 0,
  "errors": [],
  "code": 200
}

Notes

• Despite the route name, this endpoint retrieves calls by an ID range, not a single call ID.
• after is required and must be a valid integer call ID.
• before is optional and can be used to set an upper ID bound.
• Results are ordered by call ID ascending.
• Up to 100 records are returned per page. Use offset with more to page through larger result sets.
• Only calls belonging to your company are returned.
• For date-based retrieval, use /api/calls/created/ instead.
• The created field in the response reflects the call start time.

Error Responses

Status Code	Meaning
400	Bad Request – The required after parameter is missing or cannot be interpreted as a valid integer.
401	Unauthorized – The API key and/or secret is missing, invalid, inactive, associated with a disabled account, or lacks permission to read calls.
405	Method Not Allowed – A method other than GET was used.
500	Internal Server Error – An unexpected server problem occurred. Not specified in Swagger.

400 response body example:

{
  "results": [],
  "errors": ["Invalid 'after' field"],
  "code": 400
}

401 response body example:

{
  "results": [],
  "errors": ["Invalid API Key"],
  "code": 401
}

405 response body example:

{
  "results": [],
  "errors": ["Method not allowed"],
  "code": 405
}