{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"1ea4e17d-5541-4b22-bffb-95199f944712","name":"Splash API v2.2","description":"Welcome to the Splash API! This information has been assembled to make it easier to navigate our API and access your Splash data. This material covers the most commonly used endpoints. With the Splash API, users can retrieve data from Splash for use in other applications such as custom event hubs or data visualization tools.\n\n# API Access\n\nUse of the API requires a _Client ID_ and a _Client Secret._ These are obtained by contacting your Customer Success Manager and discussing your API needs. Once the Client ID and Client Secret are generated, they can be delivered via a secure, cryptographic messaging app.\n\nWhen working with the Splash API, here are some best practices to keep in mind:\n\n1. **Rate Limiting**: Ensure you pace your API calls appropriately to prevent overloading the system.\n    \n2. **Access Token Reuse**: Reusing the same access token for multiple requests can help streamline authentication and reduce overhead.\n    \n3. **Token Refresh Flow**: Implement the token refresh flow to maintain secure and continuous access, especially for long-running operations.\n    \n4. **Response Caching**: Utilizing response caching can minimize redundant requests and improve response times for frequently accessed data.\n    \n\nAlso, consider using the Simple Postback (outgoing webhook) integration, which offers real-time, UI-based configuration at the organization or event/theme level, and doesn't count against your API call limit. This integration can fulfill many use cases for retrieving Splash data effectively.\n\n# Requests\n\nAll valid Splash API requests begin with the domain: [https://api.splashthat.com/](https://api.splashthat.com/) From there, the remainder of a request is built on five separate elements.\n\n## Endpoint\n\nThe API is typically grouped into four top-level endpoints, each interacting with a Splash Object.\n\n- **/oauth/v2/token**: This authentication endpoint is where any API project begins. It handles the process of retrieving and refreshing access tokens to authorize all of your other calls.\n    \n- **/events**: This endpoint is used for handling events. While events may be retrieved, updated, and even deleted, it is very important to understand that event creation is handled via a separate API process.\n    \n- **/groupcontacts (guests)**: GroupContacts is an internal programmatic term for Splash event _guests_. This is your go-to endpoint for anything involving creating, retrieving, or updating them.\n    \n- **/contacts**: Splash separates its attendee data into two levels. GroupContacts (guests) are associated with individual events, whereas Contacts are records that exist at the organizational level and associate your GroupContacts (guests) across your different events. If you want to interact not just with a guest as they pertain to one event but as they pertain to all of your events, this is the endpoint to use.\n    \n- **/crm/events**: Creating events programmatically goes through a separate API. It requires a special API key, and we recommend consulting with our team before making use of the endpoint. It is a potent endpoint, and technical assistance in making use of it is crucial to success.\n    \n\n## Verb\n\nEndpoints typically accept one or more of five methods/verbs:\n\n- **GET**: fetch an object's data\n    \n- **POST**: create an object\n    \n- **PUT/PATCH**: update an object\n    \n- **DELETE**: delete an object\n    \n\n## Path Parameters\n\nPath parameters come into play when interacting with individual Splash objects, such as a single event or a single contact. Each of these has a unique ID number, which is placed in the request path. Any remaining information is conveyed via query parameters.\n\n## Query Parameters\n\nMany API interactions include query parameters but they are especially important in GET requests. Chiefly, they are used to filter, search, sort, and paginate the results so that the size and content of responses can be controlled.\n\n## Request Body\n\nRequest bodies are not used in all calls, and with rare exceptions only come into play when creating or updating an object. When they are used, they are in JSON format. Beyond this, there are no wider considerations regarding fields or formatting, but each endpoint that accepts JSON bodies expects a different object. These are included in the call examples for each endpoint. Refer to those as you build your requests.\n\n## Responses\n\nSplash API responses are JSON payloads, with an envelope containing the data of the response itself. Each envelope has up to three sections, allowing you to predict the keys you will be interacting with for each response.\n\n## Meta\n\nIf all is working well, the meta section displays a code 200. Should something go wrong, however, it will change to include an error type and an error message to aid in the process of debugging what exactly went wrong.\n\n## Data\n\nThe data section forms the heart of any response from Splash and it is where information on successes, failures, and most importantly the data about your Splash objects is found. Each endpoint outlined here includes examples of responses from Splash containing the data you can expect to work with.\n\n## Pagination\n\nSplash endpoints all accept explicit-type pagination with limits, pages, and total counts included in the responses to allow for easier interactions with the data. Not all responses have pagination, for instance, a DELETE request does not return a set of data, just a success or failure, rendering pagination unnecessary.\n\n## API Rate Limiting\n\nThe Splash API uses rate limiting to ensure fair usage, prevent customers from overloading resources, and maximize performance.\n\nAll requests made to the Splash API using a valid Client ID are subject to a default rate limit of **2 requests per second** (req/s). The rate limit is calculated based on the number of requests made within a rolling time window.\n\nIf a client exceeds the rate limit, the API will respond with a _429 Too Many Requests_ status code, indicating that the limit has been exceeded. This response includes a `RateLimit-Reset` header that specifies the duration in seconds, after which the client can retry the request.\n\n`{ \"message\": \"API rate limit exceeded\" }`\n\nTo comply with the rate limit, monitoring the rate of your API requests is important. You can determine the remaining limit by inspecting the headers of the API response. For example, the `X-RateLimit-Limit-Second` header indicates the total number of requests allowed within the rate limit window, and the `X-RateLimit-Remaining-Second` header shows the number of requests remaining before reaching the limit.\n\nFor more details on how to adhere to the rate limit, the benefits and impacts of rate limiting, and examples of the 429 response, refer to our Help Center article [What is API rate limiting and what are the benefits and impacts?](https://support.splashthat.com/hc/en-us/articles/13759878758541)","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"6088160","team":3935530,"collectionId":"1ea4e17d-5541-4b22-bffb-95199f944712","publishedId":"SVmvTe3o","public":true,"publicUrl":"https://api-docs.splashthat.com","privateUrl":"https://go.postman.co/documentation/6088160-1ea4e17d-5541-4b22-bffb-95199f944712","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"5230EE"},"documentationLayout":"classic-double-column","version":"8.10.1","publishDate":"2019-10-22T19:40:51.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/768118b36f06c94b0306958b980558e6915839447e859fe16906e29d683976f0","favicon":"https://splashthat.com/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://api-docs.splashthat.com/view/metadata/SVmvTe3o"}