{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"c4f662f5-2518-439d-96d4-d0ab5450fe47","name":"Convrrt API","description":"# White Label Integration Checklist\n\n# Step1: Set up custom domains for SaaS\n\nWe have a few one time setup requirements to configure domains on our SaaS solution.\n\nThe domains named `yourdomain.com` are simply suggestions. Feel free to selected any \n\n**Staging Environment**\n`CNAME` → beta.pages.yourdomain.com → staging.builder.convrrt.com\n\n**Production Environment**\n`CNAME` → pages.yourdomain.com → production.builder.convrrt.com\n\n**CDN DNS**\nThese domains are used to serve landing page traffic for your customers as well as give you a custom `CNAME` record that your customers can point to when they use custom domains.\n\n**NOTICE:** Set up the next two `CNAME` records on a separate `FQDN` to minimize the risk of XSS and cluttering your primary domains SEO.\n\nThis first record will be used by your customers to attach their custom domains to websites.\n\n`CNAME` → sites.yourdomain.net → sites.convrrt.zone\n\n`CNAME` → *.sites.yourdomain.net → sites.convrrt.zone\n\nThe star (wildcard) subdomain will be used to resolve websites that do not have a custom domain but use an internal slug I.E (nike-x12tbs.sites.yourdomain.com)\n\n**Wild Card Certificate**\nLastly, we are not able to generate a certificate to secure this wild card domain. You will need to provide us with a certificate and private key.\n\n# Step 2: Authenticate Users Into Convrrt\n\nYou will need a JSON Web Token library. You can find one for your language of choice [here](https://jwt.io/).\nThen we will provide you with a shared secret via `pgp` or `keybase` that you can sign your JWT with.\nYour developers will need to set the JWT token as a cookie on `_pages_session`  → `.yourdomain.com` this way you can control their session as well as access resources using CORS in the browser and we can see it on the subdomain.\n\n## JWT Claims\n- `*` = required\n\n| **NAME**   | **DESCRIPTION**                                                                                                                                                                                                                                                                   |\n| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| firstName  | the users first name                                                                                                                                                                                                                                                              |\n| lastName   | the users last name                                                                                                                                                                                                                                                               |\n| email*     | the users email address                                                                                                                                                                                                                                                           |\n| orgID*     | This is most often your organizations name, we use this to verify the signature on the JWT. If it’s not present we rely on the `Host` header to look this up.                                                                                                                    |\n| projectID* | a group identifier for sharing assets amongst groups of users - assets are created within a hashed namespace `orgID:projectID`. Any user identified in the same group will have access to the same assets as all other users with the same combination of `orgID` and `projectID` |\n| userId*    | The users internal identifier from your system                                                                                                                                                                                                                                    |\n\n**Example JWT**\n\n    {\n      \"firstName\": \"John\",\n      \"lastName\": \"Doe\",\n      \"email\": \"jeffy.dahmor@gmail.com\",\n      \"orgID\": \"your-org-id\",\n      \"projectID\": \"randomInternalGroupName\",\n      \"userId\": \"80982a83-a7e9-5cea-85a9-2488f13ea6ff\"\n    }\n\n**Note:** We may change from HMAC to RSA in the future using JSON Web Keys to encrypt JSON Web Tokens.\n\n# Step 3: Redirect users to Convrrt\n\nOnce the previous steps have been completed and the cookie is set on your domain. You can redirect the visitor to our system for a seamless integration.\n\nIf the user is creating a new site send them here\nhttps://pages.yourdomain.com/choose-a-template\n\nIf the user is attempting to edit an existing site send them here\nhttps://pages.yourdomain.com/editor/:siteId\n\nTo ensure the user is able to get back to where they came from you can include a `?redirectUrl=` parameter when you send them to convrrt. This way we can redirect them back when they are finished.\n\nOnce the cookie is set you can access resources in convrrt through CORS in the browser or the server to our API.\n\n**List all sites that belong to the current** `**appId**`\n`GET` https://pages.yourdomain.com/api/v1/sites\n\nYou can use our API’s to build a custom dashboard for managing landing pages.\nAll our ID’s are `uuidV4` so you can safely store them in your system for reference.\nJust remember they are scoped to the `projectID` set in the JWT.\n\n**Documentation**\nhttps://developers.convrrt.com\n\n# Event Hooks\n\nOur system can publish critical events / data to your platform using webhook standards.\nOnce you supply us with an endpoint to deliver payloads to you will receive a `POST` message that includes an `X-Event-Signature` header.\nThe value of this header is calculated using this formula `HMAC(algorithm='sha256', key='JWTSigningKey', payload='JSONEncodedBody', digest='hex')`.\n\nOnce subscribed the JSON payloads will be in this format.\n```json\n{\n  \"id\": \"ca9f95d4-806d-461a-bcad-5a7367ec30e8\",\n  \"type\": \"form_submission\",\n  \"orgID\": \"ORG_ID\",\n  \"projectID\": \"PROJECT_ID\",\n  \"userID\": \"USER_ID\",\n  \"createdAt\": \"2019-03-27T12:53:58.635Z\",\n  \"data\": {\n  }\n}\n```\n\nThe `data` value can vary based on `type`. `projectID` maps to the internal grouping you created for a subset of your users when setting the claims in your `JWT`. `userID` may or may not be populated with a known value unless you set that claim manually.\n\n## `form_submission` event\n```json\n{\n  \"id\": \"ca9f95d4-806d-461a-bcad-5a7367ec30e8\",\n  \"type\": \"form_submission\",\n  \"orgID\": \"ORG_ID\",\n  \"projectID\": \"PROJECT_ID\",\n  \"userID\": \"USER_ID\",\n  \"createdAt\": \"2019-03-27T12:53:58.635Z\",\n  \"data\": {\n    \"siteID\": \"3d945e54-9d14-436c-b345-34662b059caa\",\n    \"fields\": [\n      {\n        \"id\": \"given_name\",\n        \"value\": \"John\"\n      },\n      {\n        \"id\": \"family_name\",\n        \"value\": \"Doe\"\n      },\n      {\n        \"id\": \"email\",\n        \"value\": \"john.doe@yahoo.com\"\n      },\n      {\n        \"id\": \"phone\",\n        \"value\": \"+15417491245\"\n      },\n      {\n        \"id\": \"0d733eb1-50ed-4726-97b8-19a0a750aff7\",\n        \"value\": true\n      }\n    ]\n  }\n}\n```","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"16698","team":3543816,"collectionId":"c4f662f5-2518-439d-96d4-d0ab5450fe47","publishedId":"RWaLwo6P","public":true,"publicUrl":"https://developers.convrrt.com","privateUrl":"https://go.postman.co/documentation/16698-c4f662f5-2518-439d-96d4-d0ab5450fe47","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"5D62DC"},"documentationLayout":"classic-double-column","version":"8.10.1","publishDate":"2018-09-19T00:14:14.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/7296fbcbc90209a5f89181f1e6cd930ba36f6d034811743daa9fbfa3927bfc91","favicon":"https://convrrt.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://developers.convrrt.com/view/metadata/RWaLwo6P"}