Last updated on
September 5, 2024
Public API
Our API documentation provides all the tools and information you need to seamlessly integrate with our platform.
The following is a list of the integrations supported by our system, highlighting key features and benefits. Click on any of the below integrations to explore detailed guides and connect the right tools to your system(s).
Native integrations
Getting started with Dynamic form
Create a dynamic form within a few minutes and embed it on your own and/ or business website. Dynamic forms can be customized to serve various purposes. Here are a few ways in which Dynamic forms can be customized:
Serviceform Public API Documentation
Version: 1.0.1
Specification: OAS 3.0
Swagger / Base URL: https://link.serviceform.com
Overview
The Serviceform Public API provides access to various endpoints for managing flex spaces, leads, and chat histories. Below is a summary of key endpoints available for flex-related operations.
Swagger documentation can be found here: https://link.serviceform.com
Authorisation
To interact with these endpoints, an API key (sf-api-key) is required. Unauthorized requests will result in a 403 response status.
Media Type
Responses are provided in application/json format.
Flex-Related Endpoints
1. Get Spaces
Endpoint: GET /flex/spaces
Description: Retrieve a list of all spaces.
Parameters: None
Responses: some text
-200: Successful response with a JSON array of spaces.
-403: Request failed due to an invalid API key.
Example Response:{
{
"id": "string",
"name": "string",
"fields": [
{
"machine": "string",
"name": "string",
"id": "string",
"type": "string",
"options": [
{
"machine": "string",
"label": "string",
"value": "string"
}
]
}
]
}
2. Get Items for a Specific Space
- Endpoint: GET /flex/spaces/{spaceId}/items
- Description: Retrieve items for a specific space identified by {spaceId}.
- Parameters:
- spaceId (string, required): ID of the space.
- Responses:
- 200: Successful response with items for the specified space.
- 403: Unauthorized access due to an invalid API key.
- 404: Space not found.
- Example Response:
[{
"last_updater": "string",
"uid": "string",
"clientId": "string",
"created": "2024-08-30T05:48:46.195Z",
"id": "string",
"updated": "2024-08-30T05:48:46.195Z",
"uuid": "string",
"space_id": "string",
"primary_field": "string"
}]
3. Create a New Item in a Specific Space
- Endpoint: POST /flex/spaces/{spaceId}/items
- Description: Create a new item within a specified space.
- Parameters:
- spaceId (string, required): ID of the space.
- Request Body:
{"primary_field": "string"}
- Responses:
- 200: Successfully created the item.
- 403: Unauthorized access due to an invalid API key.
- 422: Bad request with missing or invalid data.
4. Get a Specific Item from a Space
- Endpoint: GET /flex/spaces/{spaceId}/items/{itemId}
- Description: Retrieve a specific item from a space using {spaceId} and {itemId}.
- Parameters:
- spaceId (string, required): ID of the space.
- itemId (string, required): ID of the item.
- Responses:
- 200: Successful response with the specified item.
- 403: Unauthorized access due to an invalid API key.
- 404: Item not found.
- Example Response:
{"last_updater": "string",
"uid": "string",
"clientId": "string",
"created": "2024-08-30T05:48:46.199Z",
"id": "string",
"updated": "2024-08-30T05:48:46.199Z",
"uuid": "string",
"space_id": "string",
"primary_field": "string"}
5. Update an Item in a Specific Space
- Endpoint: PUT /flex/spaces/{spaceId}/items/{itemId}
- Description: Update an item within a specific space.
- Parameters:
- spaceId (string, required): ID of the space.
- itemId (string, required): ID of the item.
- Request Body:
{"primary_field": "string"}
- Responses:
- 200: Successfully updated the item.
- 400: Bad request with missing or invalid data.
- 403: Unauthorized access due to an invalid API key.
- 404: Item not found.
- 422: Bad request with missing or invalid data.
6. Delete an Item from a Specific Space
- Endpoint: DELETE /flex/spaces/{spaceId}/items/{itemId}
- Description: Delete an item from a specific space.
- Parameters:
- spaceId (string, required): ID of the space.
- itemId (string, required): ID of the item.
- Responses:
- 200: Successfully deleted the item.
- 403: Unauthorized access due to an invalid API key.
- 404: Item not found.
7. Delete an Item from a Specific Space
- Endpoint: DELETE /flex/spaces/{spaceId}/items/{itemId}
- Description: Deletes an item from a specific space identified by the spaceId and itemId.
- Parameters:
- spaceId (string, required): ID of the space.
- itemId (string, required): ID of the item.
- Responses:
- 200 OK: Successfully deleted the item.
- 403 Forbidden: Unauthorized. The provided sf-api-key is invalid.
- 404 Not Found: The requested item was not found.
Leads endpoint
1. Get Leads
- Endpoint: GET /leads
- Description: Retrieves a list of leads.
- Parameters: None
- Responses:
- 200 OK: Successfully retrieved the leads.
{
"id": "string",
"page_url": "string",
"pid": "string",
"language": "string",
"source": "string",
"tools": [{ "tid": "string" }],
"tid": "string",
"sid": "string",
"duration": 0,
"uid": "string",
"pageviews": 0,
"pages": [{ "duration": 0, "referrer": "string", "website": "string" }],
"browser": "string",
"tokens": [{}],
"first_name": "string",
"email": "string",
"timestamp": "2024-08-30T05:48:46.202Z",
"tool_name": "string",
"os": "string",
"indexed": true,
"created": "2024-08-30T05:48:46.202Z",
"mobile": true,
"last_name": "string",
"history": [
{ "id": "string", "message": "string", "type": "string", "timestamp": 0 }
],
"referrer": "string",
"site": "string",
"phone": "string",
"name": "string",
"page": "string",
"referrer_url": "string",
"updated": "2024-08-30T05:48:46.202Z",
"space_id": "string"
}
- 401 Unauthorized: The provided sf-api-key is invalid.
Chat history
1. Get all chats
- Endpoint: POST /chats
- Description: Retrieves the chat history based on specified filters such as time range, user ID, and message details.
- Headers:
- sf-api-key: (string, required) Your API key for authentication.
- Parameters: None
- Request Body:
- Fields:
- startTime (string, optional): Start of the time range in ISO 8601 format.
- endTime (string, optional): End of the time range in ISO 8601 format.
- uid (string, optional): User ID to filter the chats.
- limit (integer, optional): Maximum number of chat records to return.
- showMessages (boolean, optional): Whether to include chat messages in the response.
- chatbot (boolean, optional): Filter chats to include only those with chatbot interactions.
- Example Request:
{
"startTime": "2024-08-30T05:48:46.204Z",
"endTime": "2024-08-30T05:48:46.204Z",
"uid": "user123",
"limit": 10,
"showMessages": true,
"chatbot": true
}
- Responses:
- 200 OK: Successfully retrieved the chat history.
[
{
"cid": "chat123",
"agentEmail": "agent@example.com",
"agentId": "agent123",
"agentName": "John Doe",
"agentJoinedTime": 1672531200,
"avgBetweenMsg": 30,
"business_phone": "+1234567890",
"phone": "+1234567890",
"first_name": "Jane",
"last_name": "Doe",
"name": "Jane Doe",
"fullUrl": "https://example.com/chat",
"lastLiveMsg": 1672531300,
"changed": 1672531400,
"lastMessage": "Thank you for your inquiry!",
"lastMessageTime": 1672531350,
"lastSender": "agent",
"leadSentTo": "sales@example.com",
"livechat": 1,
"livechatStarted": 1672531200,
"msgType": "text",
"regNo": "ABC123",
"session": "session123",
"sid": "site123",
"sitename": "Example Site",
"source": "website",
"team": "Support",
"uid": "user123",
"url": "/support/chat",
"history": [
{
"id": "msg1",
"message": "Hello, how can I help you?",
"type": "text",
"timestamp": 1672531250
},
{
"id": "msg2",
"message": "I have a question about your service.",
"type": "text",
"timestamp": 1672531280
}
]
}
]
- 403 Forbidden: Unauthorized. The provided sf-api-key is invalid.
2. Get chat statistics
- Endpoint: GET /statistics/chat
- Description: Retrieves chat-related statistics, including key performance indicators and aggregated data about chats.
- Headers:some text
- sf-api-key: (string, required) Your API key for authentication.
- Parameters:some text
- startTime (string, optional): Start of the time range in ISO 8601 format.
- endTime (string, optional): End of the time range in ISO 8601 format.
- metrics (array of strings, optional): List of specific metrics to retrieve.
- Responses:some text
- 200 OK: Successfully retrieved chat statistics.some text
{
"totalChats": 150,
"averageResponseTime": 45, // in seconds
"satisfactionScore": 4.5, // out of 5
"chatsByAgent": [
{
"agentId": "agent123",
"agentName": "John Doe",
"totalChats": 50,
"averageResponseTime": 30
},
{
"agentId": "agent124",
"agentName": "Jane Smith",
"totalChats": 100,
"averageResponseTime": 50
}
],
"chatsBySource": { "website": 120, "mobile": 30 },
"chatDurations": { "0-5 minutes": 60, "5-10 minutes": 40, "10+ minutes": 50 }
}
- 400 Bad Request: Invalid parameters or missing required data.
- 403 Forbidden: Unauthorized. The provided sf-api-key is invalid.
This documentation provides a comprehensive overview of the /chats and /statistics/chat endpoints, including their functionalities, parameters, request structures, and response formats. If you need further details or have additional requests, feel free to ask!
%20-%20Copy.png)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.png)
.svg)
