{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"57964834-3b94-405f-ab5f-adb49dc3ad49","name":"Verse External API","description":"# Overview\n\nVerse's external API offers robust functionality for conversation (Lead) management and webhook subscriptions, enabling seamless integration with your existing workflows. The API supports creating Conversations (leads) via a POST method and subscribing to multiple webhook activity types to receive updates about Verse's engagement with your leads. These activity types provide varying levels of detail about interactions within a Conversation.\n\n### Getting Started\n\n#### **For Conversation (Lead) Creation Only**\n\nIf your primary goal is to send Conversations to Verse without requiring updates, you can proceed directly to the **Create Lead POST** section. This will cover all the necessary steps to perform that action.\n\n#### **For Conversation (Lead) Updates via Webhooks**\n\nIf you aim to send Conversations (leads) and also receive updates on Conversation (lead) activity, you’ll need to review the **Webhooks** folder.\n\n- Work with your Account Manager to set up **customized scripting**. While this document provides sample configurations \"For Position Only,\" the field names in the payloads will remain consistent, but the data will be tailored to your specific needs. Scripts are custom-built for your organization, ensuring they align with your business use cases.\n    \n\n### Managing Conversations\n\n#### **Use Case: Ending Conversations**\n\nDo you anticipate needing to stop Verse from engaging with a Customer because your team has already connected with them? If so, consider the **End Conversation** and **Stop Conversation** endpoints:\n\n- **End Conversation**: Marks the Conversation as **Qualified**.\n    \n- **Stop Conversation**: Marks the Conversation as **Unqualified**.\n    \n- **DNC (Opt-Out)**: Marks the Conversation as **Unqualified** and adds the Customer to your Do Not Contact List within Verse to prevent future engagement.\n    \n\nDeciding between these endpoints depends on whether you want the Conversation to be categorized as qualified or unqualified when halting Verse’s engagement.\n\n### Account and Subscription Management\n\n#### **Single vs. Multiple Accounts**\n\nThe API key you use determines the account or system where actions are performed. If you manage multiple accounts, consider the following:\n\n- Use the **Primary API Key** for a team subscription to receive webhook events for all team members.\n    \n- Alternatively, create individual subscriptions for each team member if you need events routed to unique URLs.\n    \n\n**Use Case:**\n\n- Subscribe to all events at a team level for centralized updates.\n    \n- Route events for sub-accounts or individual team members to their respective URLs for distributed updates.\n    \n\n### Conclusion\n\nOnce you've determined your use case and integration needs, you can begin leveraging the Verse API and webhooks to optimize your Conversation (lead) management process. For further assistance, consult your Account Manager or refer to the detailed sections in this document.\n\n#### Notable Changes\n\nHistorically the individual \"Conversations\" were referred to as \"Leads\" hence many of the end points referencing the word \"lead\". As we've grown however lead doesn't adequately capture the type of engagement that is performed by Verse.\n\nThis documentation has thus been changed to reference \"Customers\" And \"Conversations\", where a Customer is the individual we engage with, however we may engage with a Customer over many conversations (leads). Please note that future versions of the external API will be updated to reflect this change, however the current API will still reference \"Leads\" in its endpoints and webhook activities.\n\n# Error Codes\n\nThe following HTTP response codes are used to determine the status of an API request.\n\n| Code | **Message Response** | Explanation |\n| --- | --- | --- |\n| 200 | {\"status\": \"success\"} | Your API request was successful |\n| 201 | {\"message\": \"Created Lead\", \"id\": \"1234567890\"} | Successful request, Conversation (lead) was created as expected |\n| 201 | {\"message\": \"Created lead, but phone is invalid, and no email was provided\", \"id\": \"1234567890\"} | Successful request, Conversation (Lead) was created however the phone provided was not valid and no email address was provided |\n| 201 | {\"message\": \"Created lead, but phone was previously blacklisted\", \"id\": \"1234567890\"} | Successful request, Conversation (lead) was created, however the phone number provided is on your blacklist. |\n| 201 | {\"message\": \"Created lead, but phone is invalid, email was valid\", \"id\": \"1234567890\"} | Successful request, Conversation (lead) was created, however the phone was invalid but the email was valid. |\n| 201 | {\"message\": \"Created lead, but email is invalid, phone was valid\", \"id\": \"1234567890\"} | Successful request, Conversation (lead) was created, however the email was invalid but the phone was valid. |\n| 401 | {\"message\": \"Unauthorized\"} | Missing or invalid authentication key/token |\n| 403 | {\"message\": \"Missing Authentication Token\"} | Your update action was attempted successfully, however the Conversation (lead) was not found. |\n| 404 | {\"message\": \"Resource Not Found\"} | You attempted to perform an action on a Conversation (lead) that was not found. |\n| 409 | {\"message\": \"Duplicate Lead\"} | Requested conflicts with another request, duplicate Conversation (lead), is still active. |\n| 422 | {\"message\": \"Your account is not set up to receive leads at this time. If you would like to make a change, please contact your account manager. \"} | Your account is set up to reject Convesations (leads) during a certain period of the day. Verse will reject Conversations (leads) that are sent to us during this time frame. If you would like to update this time, please contact your account manager. |\n| 422 | {\"message\": \"Your account is currently on hold. Please contact your account manager if you would like to reactivate.\"} | Your account is currently on hold, and is not accepting new Conversations (leads). If you'd like to activate your account again, please contact your account manager. |\n| 422 | {\"message\": \"phone is invalid\"} | The phone number is invalid and the Conversation (lead) was not created. |\n| 422 | {\"message\": \"Invalid request body\"} | The JSON provided is not valid, please check your data and try again. |\n| 422 | {\"message\": \"\"phone\" is required\"} | This may be phone, or email, the Conversation (lead) was not created. |\n| 500 | {\"message\": \"Something went wrong. If this error continues, please contact your account manager.\"} | Verse server error |","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"14869652","team":100379,"collectionId":"57964834-3b94-405f-ab5f-adb49dc3ad49","publishedId":"TzCL9UNR","public":true,"publicUrl":"https://developer.verse.io","privateUrl":"https://go.postman.co/documentation/14869652-57964834-3b94-405f-ab5f-adb49dc3ad49","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"documentationLayout":"classic-double-column","customisation":null,"version":"8.11.8","publishDate":"2021-04-01T22:48:56.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{},"logos":{}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/aa46c9ed785b960ff62013881ccd9c2465c841dc111eea23f69ea3067f24c764","favicon":"https://verse.io/favicon.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://developer.verse.io/view/metadata/TzCL9UNR"}