Dialpad WFM API (Formerly Surfboard) (1.0.0)

Download OpenAPI specification:

This is the API specification for Dialpad WFM. Our API is JSON-encoded and follows a REST style.

Authentication

To access the API, you can reach out to your customer success manager who will provide you securely with an access token which is valid for one year.

This token should be included in any requests you make to Surfboard’s API in the Authorization header in 'bearer token' format, like so:

curl 'https://api.teamsurfboard.com/api/v1/...' \
  -H 'Authorization: Bearer ...'

API requests without authentication will fail.

Rate limiting

The API enforces a rate limit of 60 requests per minute to ensure stability. Once this limit is exceeded, the API will respond with a status code of 429.

Versioning

Over time, new endpoints will be made available and existing endpoints may evolve, but backwards compability will be maintained. Fields will not be removed from response payloads, but new fields may be added to existing endpoints.

Any backwards-incompatible changes will be made in a new version of the API, and existing versions will remain functional.

Get schedule

Returns the published schedule within the specified date range.

query Parameters

start required	string Example: start=2024-06-25T00:00:00.000Z A date string in RFC 3339 format.
end required	string Example: end=2024-06-25T00:00:00.000Z A date string in RFC 3339 format.
page[size]	number Default: 100 The maximum number of entities to be returned in one response.
page[after]	string The pagination cursor to be used for the next response. If a response has more than one page, the full URL for the next page (including the appropriate page[after] parameter) will be included in the /links/next field in the response payload.

Responses

Response samples

200
400
401
429
500

Content type

application/json

{"data": [{"type": "shift",
"surfer": {"id": "1",
"email": "john.doe@example.com"
},
"interval": {"start": "2024-06-25T09:00:00.000Z",
"end": "2024-06-25T17:00:00.000Z"
},
"shiftTemplate": {"id": "7",
"name": "Regular nine to five"
},
"taskSchedule": [{"interval": {"start": "2024-06-25T09:00:00.000Z",
"end": "2024-06-25T12:00:00.000Z"
},
"task": {"type": "activity",
"id": "10",
"name": "Phones",
"ticketGroups": [{"id": "100",
"name": "General Support",
"connectedTicketingSystem": "zendesk"
}
]
}
},
{"interval": {"start": "2024-06-25T12:00:00.000Z",
"end": "2024-06-25T13:00:00.000Z"
},
"task": {"type": "break",
"id": "20",
"name": "Lunch"
}
},
{"interval": {"start": "2024-06-25T13:00:00.000Z",
"end": "2024-06-25T16:30:00.000Z"
},
"task": {"type": "activity",
"id": "11",
"name": "Email",
"ticketGroups": [{"id": "101",
"name": "VIP Support",
"connectedTicketingSystem": "zendesk"
}
]
}
},
{"interval": {"start": "2024-06-25T16:30:00.000Z",
"end": "2024-06-25T17:00:00.000Z"
},
"task": {"type": "blocked-time",
"name": "Team Meeting"
}
}
]
},
{"type": "time-off",
"subtype": "Holiday",
"remoteSubtype": "Annual Leave",
"surfer": {"id": "2",
"email": "jane.smith@example.com"
},
"interval": {"start": "2024-06-25T00:00:00.000Z",
"end": "2024-06-25T23:59:59.999Z"
}
}
],
"links": {"self": "https://api.teamsurfboard.com/api/v1/schedule?start=2024-06-25T00:00:00.000Z&end=2024-06-25T23:59:59.999Z&page[size]=100",
"next": null
}
}

Get detailed agent metrics

Returns detailed performance metrics for agents with pagination support.

query Parameters

start required	string Example: start=2024-06-25T00:00:00.000Z A date string in RFC 3339 format.
end required	string Example: end=2024-06-25T00:00:00.000Z A date string in RFC 3339 format.
emails	string Optional comma-separated list of agent emails to filter by
limit	number Default: 500 Maximum number of records to return (default: 500, max: 500)
cursor	string Pagination cursor for retrieving the next set of results

Responses

Response samples

200
400
401
429
500

Content type

application/json

{"items": [{"interval": {"start": "2024-06-25T00:00:00.000Z",
"end": "2024-06-25T23:59:59.999Z"
},
"agent": {"name": "John Doe",
"email": "john.doe@example.com"
},
"scheduled_hours": 8.5,
"utilisation": 0.75,
"total_conversations_closed": 15,
"conversations_closed_per_hour": 2.5,
"conversations_closed_per_service_hour": 3.2,
"time_on_task": 0.85,
"occupancy": 0.78,
"time_in_adherence": 25200,
"time_out_of_adherence": 1800,
"time_in_exception": 900,
"adherence_score": 92.5,
"timeInAdherence": {"seconds": 1200,
"percentage": 1
},
"timeOutOfAdherence": {"seconds": 0,
"percentage": 0
},
"timeInException": {"seconds": 0,
"percentage": 0
},
"adherenceScore": 1
}
],
"cursor": "string"
}

Get detailed activity metrics

Returns detailed performance metrics for activities with pagination support.

query Parameters

start required	string Example: start=2024-06-25T00:00:00.000Z A date string in RFC 3339 format.
end required	string Example: end=2024-06-25T00:00:00.000Z A date string in RFC 3339 format.
emails	string Optional comma-separated list of agent emails to filter by
limit	number Default: 500 Maximum number of records to return (default: 500, max: 500)
cursor	string Pagination cursor for retrieving the next set of results

Responses

Response samples

200
400
401
429
500

Content type

application/json

{"items": [{"interval": {"start": "2024-06-25T00:00:00.000Z",
"end": "2024-06-25T23:59:59.999Z"
},
"activity": {"name": "Phones",
"type": "activity"
},
"scheduled_hours": 6.5,
"time_on_task": 0.78,
"conversations_opened": 12,
"conversations_commented_on": 18,
"conversations_on_hold": 3,
"conversations_closed": 10,
"average_interaction_time": 240,
"average_conversation_time": 420,
"wrong_task_snapshots": 2,
"conversations_closed_per_hour": 1.8
}
],
"cursor": "string"
}

(DEPRECATED) Get agent metrics

⚠️ DEPRECATED: Please migrate to GET /metrics/agent endpoint.

Migration Guide

Key Differences:

Timezone Handling:
- Old: Accepts timezone parameter, aggregates data in that timezone
- New: Works exclusively with UTC timestamps, no timezone parameter
Data Aggregation:
- Old: Returns data pre-aggregated into daily buckets based on timezone
- New: Returns data in 24-hour intervals between start and end dates
- New: Each entry includes an interval field showing the exact UTC time range for that data
Response Format:
- Old: Array of agents, each with array of daily data
- New: Flat array in items field, with interval, agent, and metric fields
Pagination:
- Old: Returns all data at once (max 90 days)
- New: Requires cursor-based pagination, check cursor field for next page

Migration Example:

To replicate a 7-day query with daily aggregation:

Old endpoint: Single request with timezone, get 7 daily buckets
New endpoint: Request full 7-day range, receive data split into 24-hour intervals
Important: You MUST handle pagination - if cursor is returned, make additional requests

query Parameters

start required	string Example: start=2024-06-25T00:00:00.000Z A date string in RFC 3339 format.
end required	string Example: end=2024-06-25T00:00:00.000Z A date string in RFC 3339 format.
timezone	string Default: "Etc/UTC" Example: timezone=America/New_York IANA timezone identifier to get response metrics in
emails	string Optional comma-separated list of agent emails to filter by
includeDeletedSurfers	boolean Example: includeDeletedSurfers=true Include deleted surfers in the response

Responses

Response samples

200
400
401
429
500

Content type

application/json

[{"agent": "John Doe",
"agentEmail": "john.doe@example.com",
"data": [{"date": "2024-06-25",
"scheduledHours": 8,
"utilisation": "50.5%",
"totalConversationsClosed": 10,
"conversationsClosedPerHour": 10,
"conversationsClosedPerServiceHour": 10,
"timeOnTask": "50.5%",
"occupancy": "50.5%"
},
{"date": "2024-06-26",
"scheduledHours": 8,
"utilisation": "45.5%",
"totalConversationsClosed": 10,
"conversationsClosedPerHour": 10,
"conversationsClosedPerServiceHour": 10,
"timeOnTask": "50.5%",
"occupancy": "45.5%"
}
]
},
{"agent": "Jane Smith",
"agentEmail": "jane.smith@example.com",
"data": [{"date": "2024-06-25",
"scheduledHours": 8,
"utilisation": "50.5%",
"totalConversationsClosed": 10,
"conversationsClosedPerHour": 10,
"conversationsClosedPerServiceHour": 10,
"timeOnTask": "50.5%",
"occupancy": "50.5%"
},
{"date": "2024-06-26",
"scheduledHours": 8,
"utilisation": "45.5%",
"totalConversationsClosed": 10,
"conversationsClosedPerHour": 10,
"conversationsClosedPerServiceHour": 10,
"timeOnTask": "50.5%",
"occupancy": "45.5%"
}
]
}
]

(DEPRECATED) Get activity metrics

⚠️ DEPRECATED: Please migrate to GET /metrics/activity endpoint.

Migration Guide

Key Differences:

Timezone Handling:
- Old: Accepts timezone parameter, aggregates data in that timezone
- New: Works exclusively with UTC timestamps, no timezone parameter
Data Aggregation:
- Old: Returns data pre-aggregated into daily buckets based on timezone
- New: Returns data in 24-hour intervals between start and end dates
- New: Each entry includes an interval field showing the exact UTC time range for that data
Response Format:
- Old: Array of activities, each with array of daily data
- New: Flat array in items field, with interval, activity, and metric fields
Pagination:
- Old: Returns all data at once (max 90 days)
- New: Requires cursor-based pagination, check cursor field for next page

Migration Example:

To replicate a 7-day query with daily aggregation:

Old endpoint: Single request with timezone, get 7 daily buckets per activity
New endpoint: Request full 7-day range, receive data split into 24-hour intervals
Important: You MUST handle pagination - if cursor is returned, make additional requests

query Parameters

start required	string Example: start=2024-06-25T00:00:00.000Z A date string in RFC 3339 format.
end required	string Example: end=2024-06-25T00:00:00.000Z A date string in RFC 3339 format.
emails	string Optional comma-separated list of agent emails to filter by
timezone	string Default: "Etc/UTC" Example: timezone=America/New_York IANA timezone identifier to get response metrics in
includeDeletedSurfers	boolean Example: includeDeletedSurfers=true Include deleted surfers in the response

Responses

Response samples

200
400
401
429
500

Content type

application/json

[{"activity": "Phones",
"activityType": "activity",
"data": [{"date": "2024-06-25",
"scheduledHours": 8,
"timeOnTask": "50.5%",
"conversationsOpened": 10,
"conversationsCommentedOn": 5,
"conversationsOnHold": 2,
"conversationsClosed": 10,
"wrongTaskSnapshots": 1,
"averageInteractionTime": 10,
"averageConversationTime": 10,
"closedPerHour": 10,
"timeInAdherence": {"seconds": 0,
"percentage": 0
},
"timeOutOfAdherence": {"seconds": 0,
"percentage": 0
},
"timeInException": {"seconds": 0,
"percentage": 0
},
"adherenceScore": 0
},
{"date": "2024-06-26",
"scheduledHours": 8,
"timeOnTask": "45.5%",
"conversationsOpened": 10,
"conversationsCommentedOn": 5,
"conversationsOnHold": 2,
"conversationsClosed": 10,
"wrongTaskSnapshots": 1,
"averageInteractionTime": 10,
"averageConversationTime": 10,
"closedPerHour": 10,
"timeInAdherence": {"seconds": 0,
"percentage": 0
},
"timeOutOfAdherence": {"seconds": 0,
"percentage": 0
},
"timeInException": {"seconds": 0,
"percentage": 0
},
"adherenceScore": 0
}
]
}
]