Surfboard API (1.0.0)

Download OpenAPI specification:Download

This is the API specification for Surfboard. 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/...' \
  -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/v1/schedule?start=2024-06-25T00:00:00.000Z&end=2024-06-25T23:59:59.999Z&page[size]=100",
"next": null
}
}