{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"1943add0-dce2-4aa3-8bdb-90a41bc2fefa","name":"Pulse Engagement Cloud API","description":"# Pulse Engagement Cloud API Documentation\n\nThe **Pulse Engagement Cloud API** is meticulously designed following the principles of Representational State Transfer ([<b>REST</b>](http://en.wikipedia.org/wiki/Representational_State_Transfer)). This architectural style defines our API's foundation, where resource-oriented URLs serve as pathways to interact with the system. Requests are expected to be in JSON-encoded format, and responses are delivered in the same JSON encoding. Standard HTTP response codes ensure clarity in API interactions.\n\nFor your development convenience and the preservation of live/production data integrity, we offer the provision of a staging environment. This environment is isolated from your live/production data and is intended for testing purposes. Should you find value in this environment, don't hesitate to reach out to your dedicated Pulse Health account manager. They will be more than willing to set up this environment for you.\n\nUnderstanding that each account has unique needs, the Pulse Engagement Cloud API adapts to cater to those needs. Custom fields and integrations, among other functionalities, are tailored to align with your account's requirements. Depending on the customization needed, this may affect requirements and responses for different APIs.\n\n# Getting Started\n\nTo start sending requests to the Pulse Engagement Cloud API, you will need to get the values for your account's Account ID and API Token.\n\n> To get the Account ID and API Token, please ask your Pulse Health account manager. \n  \n\n### API Limitations\n\nPlease note, we currently only support API request from secure backend servers and prevent front end browsers/clients from connecting to the API.\n\n### Authorization\n\nTo authorize a request for the Pulse Engagement Cloud API, you must set request headers for the Account ID and API Token.\n\n```\nAuthorization: API-TOKEN YOUR_API_TOKEN_HERE\nX-Account: YOUR_ACCOUNT_ID_HERE\n\n ```\n\nNote: Make sure to include API-TOKEN as part of the authorization header.\n\n```\nExample:\nAuthorization: API-TOKEN xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\nX-Account: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\n\n ```\n\nIf using Postman, you can use the `{{ apiToken }}` and `{{ accountId }}` variables in the environment to set the values. For more information about environments, see [the Postman documentation](https://learning.postman.com/docs/sending-requests/managing-environments/).\n\n# Registration Forms (best practice)\n\nThere are two options for how to handle sending data for registration/sign-up forms.\n\n### **Option 1 (Recommended): Use the Form Submission API**\n\nAs of March 6th, 2024, we have created new standard for processing forms containing contact data.\n\nWe recommend using this new feature due to ease of use, and additional features such as configuration of post-submission actions (e.g., creating a form submission action).\n\n[Please view the Form Submission API documentation here](https://api-docs.pulsehealth.tech/#5e645365-b6ae-4b91-92e3-62c88bbdcc9c)\n\n### **Option 2 (Legacy): Use the Contact API**\n\nThe Contact API enpoints are a powerful tool that allows you to efficiently manage contact information. This guide will walk you through the process of performing an API lookup to search for a contact's email, creating a new contact if the email address doesn't exist, and updating the contact if the email address already exists.\n\n### **Prerequisites**\n\nBefore you begin, make sure you have the following:\n\n1. Access to the Contact Management API (including the necessary Account ID and API Token).\n    \n2. A programming environment that supports making HTTP requests. We do not support CORS so the requests should be sent from a backend server.\n    \n\n## **API Lookup and Contact Handling**\n\n**Perform an API Lookup**\n\nTo search for a contact's email address using the API, you'll typically need to make a GET request to the appropriate endpoint, passing the email address as a parameter. The API will respond with the contact's information if the email exists or with an appropriate response if the email is not found.  \nExample Request:  \n`[GET] /contacts/search?groups[]=contact_display_email&simpleSearch={EMAIL ADDRESS}`\n\n**Create a New Contact**\n\nIf the API lookup doesn't return any results, you can assume that the email address doesn't exist in the database. In this case, you can proceed to create a new contact by making a POST request to the endpoint designed for contact creation. Please note, Source is required. Also, the **custom fields section in the example below is only an example**. _Your account manager can guide you with what specific values you can pass for your specific account._\n\nExample Request:  \n`[POST] /contacts`\n\nExample Payload:\n\n``` json\n{\n  \"salutation\": \"Dr\", // Optional\n  \"firstName\": \"Example\", // Optional\n  \"middleName\": \"\", // Optional\n  \"lastName\": \"Example\", // Optional\n  \"credentials\": \"MD\", // Optional\n  \"gender\": \"M\", // Optional\n  \"npi\": \"1234567890\", // Optional - This stands for National Provider Identifier. This is a unique identifier given to doctors. Leave blank for patient data.\n  \"specialty\": \"Oncology\", // Optional\n  \"contactType\": \"HCP\", // Optional - for patient data please set as \"Patient\"/“Caregiver”/etc.\n  \"source\": 1, // Required - This will be a static number that references data you send. We can provide this value to you. Values might differ between staging and production environments.\n  \"emails\": [\n    {\n      \"emailAddress\": \"example@email.com\", // Required if saving email address\n      \"isSubscribed\": true, // Should be true if the patient is signed up for Email Messages\n    }\n  ],\n  \"locations\": [\n    {\n      \"company\": \"The Night's Watch\", // Optional\n      \"addressLine1\": \"1 Wall St.\", // Required only if storing Address Line 2, otherwise optional\n      \"addressLine2\": \"Suite 100\", // Optional\n      \"city\": \"New York\", // Required only if storing Address Line 1, otherwise optional\n      \"state\": \"NY\", // Required only if storing City and/or Address Line 1, otherwise optional\n      \"postalCode\": \"10001\", // Required only if storing Address Line 1, otherwise optional\n      \"country\": \"USA\" // Optional\n    }\n  ],\n  \"phones\": [\n    {\n      \"phone\": \"5165551212\", // Required if saving phone number\n      \"isPhoneSubscribed\": true, // Should be true if the contact is signed up for Phone Calls\n      \"isSmsSubscribed\": true, // Should be true if the contact is signed up for Text Messages\n      \"isFax\": false // Optional\n    }\n  ],\n  \"customFields\": {\n    \"sampleNumericField\": 12345, // This is just an example\n    \"sampleBoolenField\": true, // This is just an example\n    \"sampleStringField\": \"USA\" // This is just an example\n  },\n  \"isTest\": false  // Should be false for real contacts and true test contacts. \n                   // If set to true, Test contacts statistics will not calculated in reports and hidden from standard search.\n}\n\n ```\n\n**Update an Existing Contact**\n\nIf the API lookup returns a valid contact's information, you can proceed to update the contact. To do this, make a PUT request to the endpoint for updating contacts, providing the contact's ID along with the updated information.\n\nExample Request:  \n`[PUT] /contacts/{id}`\n\nExample Payload:\n\n``` json\n{\n  \"salutation\": \"Dr\", // Optional\n  \"firstName\": \"John\", // Optional\n  \"lastName\": \"Snow\", // Optional\n  \"specialty\": \"Oncology\", // Optional\n  \"emails\": [\n    {\n      \"id\": 1001, // The ID of the email address belonging to the contact\n      \"emailAddress\": \"example@email.com\", // Required if saving email address\n      \"isSubscribed\": true, // Should be true if the contact is signed up for Email Messages\n    }\n  ]\n}\n\n ```\n\n# Working with List endpoints\n\nThis API will contain endpoints to retrieve listings of different resources. Most endpoints will contain common query parameters that will help with specifying which data fields to return and sorting. If the endpoint does not allow this feature, the documentation for that endpoint will clearly state this.\n\nPlease view the resource's main folder documentation for a list of fields that can be used for field restriction and sorting.\n\n### Field Restriction\n\nThe data in the list endpoint response can be restricted to only return specific fields. To do this, you must set a query parameter for the `fields[]` array.\n\nIf no `fields[]` array exists in the request, all data is returned. This query parameter is useful in cases where you don't want or can't see certain data points.\n\nAnother use case is to optimize the response in cases of large data sets.\n\n### Sorting\n\nYou can sort the results by fields based on ascending or descending order. To do this, you must set a query parameter for the `sort[]` array.\n\nAs you can tell, since the parameter is an array, you can sort by multiple fields in the same request. The order of the sorting is dependent on the order of the values in the `sort[]` array.\n\nThe value must be formatted as `{field}:{order}`. The field and order are separated by a colon (`:`). For example, if you wanted to sort by the contact's created date to see the newest contacts first, the value would be `createdAt:DESC`. If you wanted to sort by the contact's last name in alphabetical order, the value would be `lastName:ASC`.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"10640692","team":787326,"collectionId":"1943add0-dce2-4aa3-8bdb-90a41bc2fefa","publishedId":"UzXKVdd1","public":true,"publicUrl":"https://api-docs.pulsehealth.tech","privateUrl":"https://go.postman.co/documentation/10640692-1943add0-dce2-4aa3-8bdb-90a41bc2fefa","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"328fee"},"documentationLayout":"classic-double-column","customisation":null,"version":"8.11.6","publishDate":"2022-07-22T13:43:01.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{},"logos":{}},"statusCode":200},"environments":[{"name":"PEC Production","id":"d5bc2ca3-7320-44a8-a614-15caa2e58cab","owner":"10640692","values":[{"key":"apiUrl","value":"https://API_URL","enabled":true},{"key":"apiToken","value":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","enabled":true},{"key":"accountId","value":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","enabled":true}],"published":true}],"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/b08b4e339c35734a63e9995bf9fec9565dbbd541f9acaa58b5f6db0b0c1a3c49","favicon":"https://res.cloudinary.com/postman/image/upload/v1637101709/team/ukbeddkqvn5ia9pt7nk0.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"},{"label":"PEC Production","value":"10640692-d5bc2ca3-7320-44a8-a614-15caa2e58cab"}],"canonicalUrl":"https://api-docs.pulsehealth.tech/view/metadata/UzXKVdd1"}