\n\nπͺ Get Started
\n
π Authorization
βοΈ Example Responses
π Data flow to call a lead
π€ Need Help?
Steps to get started with GetVocal's API:
\nAuthorization: Login using your GetVocal provided username and password to get a JWT token
\nAccess: Use a JWT bearer token returned by the login route (explained below). Alternatively, you can also create an API Key for your user that will give you access to the same route as your user, but don't need refreshing.
For more details, check out the additional sections below, and click View Complete Documentation for the complete documentation. If you have questions about the folder or request, look for the documentation icon for documentation-in-context.
The GetVocal API uses JWT tokens for authorization, or ApiKeys with Secrets.
\nYou must include an access token in each request to the Postman API with the Authorization request header (Bearer: XXX as the content, replacing XXX with the actual token).
X-Client-Api-Key and X-Client-Api-Key-Secret headers.The access token has been pre-filled as a collection variable. The authorization has been set up at the collection level, so all requests in this collection will automatically inherit the needed header.
\n\n\nβ Donβt leak your secrets! Initial values are saved, and can be shared with others in team workspaces. Current values are local values that are not saved, and won't be persisted in the original shared collection, environment, or globals. Learn more about variables in Postman
\n
We have documented many of the possible responses you might encounter using Examples under each request.
\nGetvocal's data flow to call a lead has 4 steps:
\nAuthenticate (JWT or ApiKeys)
\nCreate the lead
\nGet the persona id you want to trigger the call with
\nTrigger the call
\nGet the call output
\nYou can find information on each of these steps in their corresponding folders.
\nThe GetVocal team wants to ensure that your team has everything they need to successfully integrate our services into your applications and services. Don't hesitate to reach out to us at jules [at] getvocal [dot] ai
\n\nIs your team utilizing this API in a use case not represented here? We want to know about it! Add a comment with your suggestions and feedback!
\n
You should have gotten from the GetVocal team a company_id and one or more persona_id which you will use throughout this documentation
This endpoint retrieves the authenticated user's API keys.
\nThe response for this request can be represented as a JSON schema:
\n[\n {\n \"uuid_id\": \"\",\n \"name\": \"\",\n \"dt_created\": \"\",\n \"dt_revoked\": null\n }\n]\n\nThe response body is an array of objects, where each object contains the following properties:
\nuuid_id (string): The unique identifier for the API key.
name (string): The name of the API key.
dt_created (string): The date and time when the API key was created.
dt_revoked (string or null): The date and time when the API key was revoked, or null if it has not been revoked.
Please note that the secret (nor the hash of the secret that is stored in our databse) is returned. Once you create your API Key, you will receive the secret for it, and will only be able to see it once.
\n","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"0e9a953f-0e2f-4db2-949b-9bad899fb52c","id":"0e9a953f-0e2f-4db2-949b-9bad899fb52c","name":"Authentication","type":"folder"}},"urlObject":{"path":["auth","apikeys","mine"],"host":["https://nexus.production.getvocal.ai/v1"],"query":[],"variable":[]}},"response":[{"id":"db3a14cb-fb6d-45fd-81d6-f22cbe78e729","name":"Success","originalRequest":{"method":"GET","header":[],"url":"https://nexus.production.getvocal.ai/v1/auth/apikeys/mine"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"date","value":"Mon, 27 Jan 2025 08:46:22 GMT"},{"key":"server","value":"uvicorn"},{"key":"content-length","value":"164"},{"key":"content-type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"[\n {\n \"uuid_id\": \"8a0d719f-94e1-4390-b833-849f5bf299fa\",\n \"name\": \"Test Getvocal API Key\",\n \"dt_created\": \"2025-01-27T06:56:09.829791Z\",\n \"dt_revoked\": null\n }\n]"}],"_postman_id":"03d526db-a546-4a39-bedc-7515a4ee7d7e"},{"name":"Create an API Key","id":"8c28b290-d2a7-4a13-9004-75ef9fe17cb0","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"name\": \"My API Key name\"\n}","options":{"raw":{"language":"json"}}},"url":"https://nexus.production.getvocal.ai/v1/auth/apikeys","description":"This endpoint allows you to create a new API key for authentication. When making a POST request to https://nexus.production.getvocal.ai/v1/auth/apikeys, you should include the API key name in the request body.
The response will be in JSON format with the following schema:
\n{\n \"type\": \"object\",\n \"properties\": {\n \"secret\": {\n \"type\": \"string\"\n },\n \"name\": {\n \"type\": \"string\"\n },\n \"key_id\": {\n \"type\": \"string\"\n }\n }\n}\n\nThe response will include the newly created API key details such as the secret, name, and key_id.
\nExample response:
\n{\n \"secret\": \"SECRET\",\n \"name\": \"Api Key Name\",\n \"key_id\": \"ID\"\n}\n\nPlease make sure to write down the returned secret of the request, as we do not store your secrets and if you loose it, you will not be able to use this api key again.
This endpoint revokes the given API key based on the ID.
\nThe response for this request can be represented as a JSON schema:
\n[\n {\n \"uuid_id\": \"\",\n \"name\": \"\",\n \"dt_created\": \"\",\n \"dt_revoked\": null\n }\n]\n\nThe response body is an array of objects, where each object contains the following properties:
\nuuid_id (string): The unique identifier for the API key.
name (string): The name of the API key.
dt_created (string): The date and time when the API key was created.
dt_revoked (string or null): The date and time when the API key was revoked
Routes relating to getting, revoking or creating an API Key
\n","_postman_id":"e80db110-012e-41fe-b771-311426bc59f9","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"0e9a953f-0e2f-4db2-949b-9bad899fb52c","id":"0e9a953f-0e2f-4db2-949b-9bad899fb52c","name":"Authentication","type":"folder"}}},{"name":"Login","event":[{"listen":"test","script":{"id":"1dc59d2e-ef88-44b0-bc25-171e1f7f6195","exec":["pm.test(\"response is ok\", ()=>{"," pm.response.to.have.status(200)","})","","var jsonData = JSON.parse(responseBody);","","pm.environment.set(\"access_token\", jsonData.access_token);","pm.environment.set(\"refresh_token\", jsonData.refresh_token)"],"type":"text/javascript","packages":{}}}],"id":"70b54e45-6689-4c56-bfe5-6b79a8e7e5b5","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"email\": \"YOUR_EMAIL_HERE\",\n \"password\": \"YOUR_PASSWORD_HERE\"\n}","options":{"raw":{"language":"json"}}},"url":"https://nexus.production.getvocal.ai/v1/auth/login","description":"Login request. Required an email and password.
\nThis request will return an access token and a refresh token. These are valid 15 minutes and 30 days respectively. The request will also return the user's id and your company id, which could be used in further requests.
\n","urlObject":{"path":["auth","login"],"host":["https://nexus.production.getvocal.ai/v1"],"query":[],"variable":[]}},"response":[{"id":"e6fbad0e-8f21-4d89-974a-5169cc69df83","name":"Login Success","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"email\": \"jules@getvocal.ai\",\n \"password\": \"password\"\n}","options":{"raw":{"language":"json"}}},"url":"https://nexus.production.getvocal.ai/v1/auth/login"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"date","value":"Wed, 02 Oct 2024 14:48:09 GMT"},{"key":"server","value":"uvicorn"},{"key":"content-length","value":"609"},{"key":"content-type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"access_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWJqZWN0Ijp7InVzZXJfaWQiOjEsImVtYWlsIjoianVsZXNAZ2V0dm9jYWwuYWkifSwidHlwZSI6ImFjY2VzcyIsImV4cCI6MTcyNzg4MTM4OSwiaWF0IjoxNzI3ODgwNDg5LCJqdGkiOiIzOTdjNTU5Ny1kZjZjLTQ3NDctODY1NS04NDk4ZGQzZGI2OTEifQ.BsdbrRkTL4pgO6wxCqfgSujpGfxqLo0f5zgE2RY1vhg\",\n \"refresh_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWJqZWN0Ijp7InVzZXJfaWQiOjEsImVtYWlsIjoianVsZXNAZ2V0dm9jYWwuYWkifSwidHlwZSI6InJlZnJlc2giLCJleHAiOjE3MzA0NzI0ODksImlhdCI6MTcyNzg4MDQ4OSwianRpIjoiOWM4MTZkNWUtODQ2ZC00Mzg5LTg4ZGMtODQ0Njk2YWE2ODc4In0.WkDcimRfw0ACcoZI5ZgpjjvKL0GcoKM5yWS9eDIn-_c\",\n \"user_id\": 1\n}"},{"id":"44d5b8b9-c56a-4207-9078-6dd3b3cb6d1e","name":"Incorrect email format","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"email\": \"YOUR_EMAIL_HERE\",\n \"password\": \"YOUR_PASSWORD_HERE\"\n}","options":{"raw":{"language":"json"}}},"url":"https://nexus.production.getvocal.ai/v1/auth/login"},"status":"Unprocessable Entity","code":422,"_postman_previewlanguage":"json","header":[{"key":"Content-Length","value":"223"},{"key":"Content-Type","value":"application/json"},{"key":"Date","value":"Tue, 14 Jan 2025 19:32:39 GMT"},{"key":"Server","value":"hypercorn-h11"}],"cookie":[],"responseTime":null,"body":"{\n \"detail\": [\n {\n \"type\": \"value_error\",\n \"loc\": [\n \"body\",\n \"email\"\n ],\n \"msg\": \"value is not a valid email address: An email address must have an @-sign.\",\n \"input\": \"YOUR_EMAIL_HERE\",\n \"ctx\": {\n \"reason\": \"An email address must have an @-sign.\"\n }\n }\n ]\n}"}],"_postman_id":"70b54e45-6689-4c56-bfe5-6b79a8e7e5b5"},{"name":"Refresh","event":[{"listen":"test","script":{"id":"1dc59d2e-ef88-44b0-bc25-171e1f7f6195","exec":["pm.test(\"response is ok\", ()=>{"," pm.response.to.have.status(200)","})","","var jsonData = JSON.parse(responseBody);","","pm.environment.set(\"access_token\", jsonData.access_token);",""],"type":"text/javascript","packages":{}}}],"id":"81120109-c668-4a3f-9e83-138cf26c12c6","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{refresh_token}}"}]},"isInherited":false},"method":"POST","header":[],"url":"https://nexus.production.getvocal.ai/v1/auth/refresh","description":"Refreshes your access token based on the refresh token provided, and returns another 15-minutes lasting access token.
\n","urlObject":{"path":["auth","refresh"],"host":["https://nexus.production.getvocal.ai/v1"],"query":[],"variable":[]}},"response":[{"id":"81c2c8ae-a456-438f-bfdb-ad3bb142a7e9","name":"Refresh success","originalRequest":{"method":"POST","header":[],"url":"https://nexus.production.getvocal.ai/v1/auth/refresh"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"date","value":"Wed, 02 Oct 2024 14:47:59 GMT"},{"key":"server","value":"uvicorn"},{"key":"content-length","value":"298"},{"key":"content-type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"access_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWJqZWN0Ijp7InVzZXJfaWQiOjEsImVtYWlsIjoianVsZXNAZ2V0dm9jYWwuYWkifSwidHlwZSI6ImFjY2VzcyIsImV4cCI6MTcyNzg4MTM3OSwiaWF0IjoxNzI3ODgwNDc5LCJqdGkiOiI3YjNiODZjOC04ZDNjLTRiODEtOWEzZC1lODdjOTkzY2RlMjQifQ.TJ1woj9D7OprBaLQ6IKkav-oZ6H0mZ5chheZPkU7PmA\"\n}"}],"_postman_id":"81120109-c668-4a3f-9e83-138cf26c12c6"}],"id":"0e9a953f-0e2f-4db2-949b-9bad899fb52c","description":"In this folder you will find all the info needed to authenticate, refresh and logout of your account using our API
\nComing soon is the ability to authenticate using client ApiKeys, allowing you to not have to login and use JWT tokens.
\n","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"id":"8e135c90-6bcb-424c-ad4e-a789b1e76d43","type":"text/javascript","packages":{},"exec":[""]}},{"listen":"test","script":{"id":"17efa593-5267-4eeb-890e-b879a0f242e5","type":"text/javascript","packages":{},"exec":[""]}}],"_postman_id":"0e9a953f-0e2f-4db2-949b-9bad899fb52c"},{"name":"Leads","item":[{"name":"Create Lead","id":"e84a5495-d915-42ac-a3a0-2fe3d64d86fd","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{access_token}}"}]},"isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"items\": [\n {\n \"phone_number\": \"+33612345678\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"email_address\": \"John.doe@example.org\",\n \"company_name\": \"Example Inc\",\n \"customer_lead_id\": \"ee406829-fe3c-4fac-bc16-9de7dee6f284\",\n \"static_data\": {\n \"DATE_OF_BIRTH\": \"06/04/1998\"\n },\n \"language\": \"fr\"\n }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"https://nexus.production.getvocal.ai/v1/leads","description":"This endpoint is used to submit leads data, one or more.
\nMethod: POST
\nBody (Json):
\nitems (array): An array of lead objects containing the following parameters:
\nphone_number (string): The phone number of the lead with the corresponding coutry code.
first_name (string)(optional): The first name of the lead.
last_name (string)(optional): The last name of the lead.
email_address (string)(optional): The email address of the lead (optional, used for example to send the lead an email if your agent is configured to do so).
company_name (string)(optional): The name of the company associated with the lead.
customer_lead_id (string)(optional): The unique ID of the lead on your end. This allows you to not have to store our own id generated for it, and query the lead using your IDs if you prefer.
static_data (object)(optional): Additional static data associated with the lead.
{\"DATE_OF_BIRTH\": \"06/04/1998\", \"FIRST_NAME\": \"John\", \"LAST_NAME\": \"Doe\"}language (string)(optional): The language of the lead (For example, fr or en).
In this folder, you will find the routes needed to create, update and delete a lead from our service.
\nA lead is a client on your side, with their attached information, someone you want to call using our service.
\n","_postman_id":"ee661163-727a-4ae1-b1bc-e3b85e6f617f","auth":{"type":"bearer","bearer":{"basicConfig":[]},"isInherited":true,"source":{"_postman_id":"87d290d0-df17-467e-9374-7688a8f1372f","id":"87d290d0-df17-467e-9374-7688a8f1372f","name":"GetVocal Reference API documentation","type":"collection"}}},{"name":"Personas","item":[{"name":"Get personas","id":"a2fac43c-1db7-41e6-b965-f7339c0fe4f1","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{access_token}}"}]},"isInherited":false},"method":"GET","header":[],"url":"https://nexus.production.getvocal.ai/v1/companies/YOUR_COMPANY_ID/personas","urlObject":{"path":["companies","YOUR_COMPANY_ID","personas"],"host":["https://nexus.production.getvocal.ai/v1"],"query":[],"variable":[]}},"response":[{"id":"719e7c68-b3bd-45e8-a6b1-5ab2f8d847c2","name":"200 OK","originalRequest":{"method":"GET","header":[],"url":"https://nexus.production.getvocal.ai/v1/companies/YOUR_COMPANY_ID/personas"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"[\n {\n \"id\": \"xxx\",\n \"name\": \"Inbound Lead Qualification\",\n \"type\": null\n },\n {\n \"id\": \"yyy\",\n \"name\": \"Outbound Lead Qualification\",\n \"type\": null\n }\n]"}],"_postman_id":"a2fac43c-1db7-41e6-b965-f7339c0fe4f1"}],"id":"3a1e44b6-7263-4145-a66e-55b5d2dcac93","_postman_id":"3a1e44b6-7263-4145-a66e-55b5d2dcac93","description":"","auth":{"type":"bearer","bearer":{"basicConfig":[]},"isInherited":true,"source":{"_postman_id":"87d290d0-df17-467e-9374-7688a8f1372f","id":"87d290d0-df17-467e-9374-7688a8f1372f","name":"GetVocal Reference API documentation","type":"collection"}}},{"name":"Calls","item":[{"name":"Trigger Call","id":"6093226e-5666-45b7-9bce-35cc40c7cdca","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{access_token}}"}]},"isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"persona_id\": \"THE_PERSONA_THAT_DOES_THE_CALL\",\n \"lead_id\": \"LEAD_ID_TO_CALL\",\n \"schedule_timestamp\": null // example value: 1737647801.7174752 // optional - this property should be set to null or 0 if we need to trigger the call and not schedule the call\n}","options":{"raw":{"language":"json"}}},"url":"https://nexus.production.getvocal.ai/v1/calls/trigger","description":"Trigger a call from a given persona to a given lead.
\n`schedule_timestamp` should be a UTC timestamp.
\n","urlObject":{"path":["calls","trigger"],"host":["https://nexus.production.getvocal.ai/v1"],"query":[],"variable":[]}},"response":[{"id":"2d029761-3ddf-4708-a413-19f52be69531","name":"200 OK","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"persona_id\": \"THE_PERSONA_THAT_DOES_THE_CALL\",\n \"lead_id\": \"LEAD_ID_TO_CALL\",\n \"schedule_timestamp\": null // example value: 1737647801.7174752 // optional - this property should be set to null if we need to trigger the call and not schedule the call\n}","options":{"raw":{"language":"json"}}},"url":"https://nexus.production.getvocal.ai/v1/calls/trigger"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"id\": \"xxx\",\n \"call_status\": \"in_queue\",\n \"lead_id\": \"GETVOCAL_LEAD_ID\",\n \"to_phone_number\": \"LEAD_PHONE_NUMBER\",\n \"from_phone_number\": \"NUMBER_GETVOCAL_IS_CALLING_WITH\",\n \"company_id\": \"YOUR_COMPANY_ID\",\n \"assistant_id\": \"ASSISTANT_ID_SELECTED_FROM_PERSONA\",\n \"start_time\": \"OPTIONAL_STRING_OF_TIMESTAMP_WHEN_CALL_WILL_BE_PLACED\",\n \"end_time\": null,\n \"conv_graph_id\": \"INTERNAL_ID_USED_BY_GETVOCAL\"\n}"},{"id":"f68cf357-0662-4a3d-bba1-9bc8936fa1bc","name":"400 Lead already in queue","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"persona_id\": \"THE_PERSONA_THAT_DOES_THE_CALL\",\n \"lead_id\": \"LEAD_ID_TO_CALL\",\n \"schedule_timestamp\": null // example value: 1737647801.7174752 // optional - this property should be set to null if we need to trigger the call and not schedule the call\n}","options":{"raw":{"language":"json"}}},"url":"https://nexus.production.getvocal.ai/v1/calls/trigger"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"message\": \"Call not triggered for lead_id LEAD_ID : already a call in queue for this lead\",\n \"name\": \"BadRequest\",\n \"status_code\": 400,\n \"solution\": \"Try again.\"\n}"},{"id":"0136a10c-ba21-4af1-a693-0f9bd8792a3a","name":"400 Max number of calls reached","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"persona_id\": \"THE_PERSONA_THAT_DOES_THE_CALL\",\n \"lead_id\": \"LEAD_ID_TO_CALL\",\n \"schedule_timestamp\": null // example value: 1737647801.7174752 // optional - this property should be set to null if we need to trigger the call and not schedule the call\n}","options":{"raw":{"language":"json"}}},"url":"https://nexus.production.getvocal.ai/v1/calls/trigger"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"message\":\"Call cannot be placed for Lead LEAD_ID - LEAD_CONTACT_NAME because the call limit has been reached or there is already call in queue\",\n \"name\": \"BadRequest\",\n \"status_code\": 400,\n \"solution\": \"Try again.\"\n}"}],"_postman_id":"6093226e-5666-45b7-9bce-35cc40c7cdca"},{"name":"Delete Scheduled Calls for Lead","id":"d4d5d052-fb26-4d32-a21b-e1cd67735035","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"