{"_id":"55d3cff27789b50d00f695d8","__v":0,"initVersion":{"_id":"53844558a43e08da4677be12","version":"1.0"},"project":"53844557a43e08da4677be0e","user":{"_id":"5384345d90c19d5e43a8170c","username":"","name":"Derek Skaletsky"},"hidden":false,"createdAt":"2015-08-19T00:38:10.624Z","fullscreen":false,"htmlmode":false,"html":"","body":"Just a quick overview of integrating with the Knowtify API.\n\nWant a quick way to test our API? Check out our [Postman collection](http://api.knowtify.io/v1.0/docs/postman). \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"What is the Knowtify API?\"\n}\n[/block]\nUnless you are interacting with Knowtify via one of our integration partners, our API will be the main way your app will talk to our platform. In this case, you will use our API to send Knowtify all the data and information you need to build and manage your different email initiatives:\n \n- For [Transactional emails](http://api.knowtify.io/docs/sending-event-based-emails), you will use our API to send event data to Knowtify as well as to trigger the email to be delivered.\n- For Behavioral emails, you will use our API to send behavioral data about your users. You should ship any data or information that you would want to use to define if and when a user should receive one of your behavioral emails. \n- For Digest emails, you will use our API to send over the data that will populate your digest emails as well as any data that will help you segment the recipient of the email and/or the sections within the email. It is typical that your app will ship data to Knowtify via our API 1-2 hours before any of your Digests are scheduled to go out.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"How does the Knowtify API work?\"\n}\n[/block]\nWe currently only offer a JSON API using token authentication. If that doesn't make sense to you, please send this to your tech team. If you are the tech team and it still doesn't make sense, please email us at success@knowtify.io and we'll help you get going.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"You can find your API token on the[ Account page](http://www.knowtify.io/settings) of your Knowtify account.\",\n  \"title\": \"Your API Token\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Request Header\"\n}\n[/block]\nWhen making a request, you will need to add the following to the request header.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Authorization: Token token=\\\"API_TOKEN\\\"\\nContent-Type: application/json\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Base URL\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"http://www.knowtify.io/api/v1\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Adding Contacts & Contact-Level Data\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"POST /contacts/upsert\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nYou can Add, Update and/or Edit any contact and his/her data with a simple UPSERT call.\n\nWhen you post contacts using the UPSERT can Knowtify recognizes the email address of the contact, it will edit the data attached to that contact.\n\nIf Knowtify doesn't recognize the email address of the contact, it will ADD a new contact.\n\nYou will get a response back with the status of your request.\n\n**Example request:** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"contacts\\\": [\\n        {\\n            \\\"name\\\":\\\"John\\\",\\n            \\\"email\\\":\\\"john@test.com\\\",\\n            \\\"data\\\":{\\n                \\\"category\\\":\\\"sports\\\",\\n                \\\"followers\\\":300\\t\\n            }\\n        },\\n        {\\n            \\\"name\\\":\\\"Samuel\\\",\\n            \\\"email\\\":\\\"sam@test.com\\\",\\n            \\\"data\\\":{\\n                \\\"category\\\":\\\"sports\\\",\\n                \\\"followers\\\":32,\\n                \\\"comments\\\":54,\\n                \\\"role\\\":\\\"Editor\\\"\\n            }\\n        }\\n    ]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Delete Contacts\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"POST /contacts/delete\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nBatch deletes require the **\"contacts\"** array to be strings of emails to be deleted.\n\nIf you accidentally send an add/edit/upsert request to the delete endpoint, an error will be thrown and the contacts will be preserved because of the formatting requirements.\n\n**Example Request**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"contacts\\\": [\\n        \\\"john@test.com\\\",\\n        \\\"sam@test.com\\\",\\n        \\\"sarah@test.com\\\",\\n        \\\"mike@test.com\\\",\\n        \\\"jill@test.com\\\",\\n        \\\"ashley@test.com\\\",\\n        \\\"frank@test.com\\\",\\n        \\\"bill@test.com\\\"\\n    ]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Edit Global Data\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"POST /data/edit\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n[Global data](http://api.knowtify.io/v1.0/docs/getting-started#two-types-of-data-in-knowtify) can be used in digest blocks by using double curly braces - **{{users}}**\n\nWhen editing global data send only the key/value pairs you want to change.\n\n**Example Request**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"data\\\": {\\n        \\\"users\\\":890,\\n        \\\"comments\\\":994,\\n        \\\"top_story_url\\\":\\\"test.com/story\\\",\\n        \\\"top_story_title\\\":\\\"Article!\\\"\\n    }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Incrementing Data Points\"\n}\n[/block]\nSometimes you just want to be able to increment or decrement one of your global or contact data points without persisting data and running simple computations on your server. Good news! Now you can make a regular API request to /data/edit or /contacts/upsert using either \"+1\" or \"-1\" as a data point value and we'll do the math on our end.\n\n##Global Data Example\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"data\\\":{\\n    \\\"total_apps_built\\\":\\\"+1\\\",\\n    \\\"days_to_launch\\\":\\\"-1\\\"\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n##Contact Data Example\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"contacts\\\": [\\n        {\\n            \\\"email\\\":\\\"contact@test.com\\\",\\n            \\\"data\\\":{\\n                \\\"downloads\\\":\\\"+1\\\",\\n              \\t\\\"friends_invited\\\":\\\"+1\\\"\\n            }\\n        }\\n   \\t]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"CONTENT LOOPS & NESTED DATA\"\n}\n[/block]\nAn overview of using more complex data structures\n\nSee our [Postman collection](http://api.knowtify.io/v1.0/docs/postman).\n\nNested data structures will be essential for many of your Digest emails. \n\nThese nested structures allow you to create more flexible sections in your emails - in the case each user/recipient of your emails have a variable number of some element you want to display in your Digest. For example, each one of your users may have a different number of Tasks due for the day, each Task having sub-data attached (Name of Task, Type of Task, Due Date, etc). In this case Tasks would be the parent data point and each element of that task would represent sub-data points (or \"children\"). One of your users may have 3 tasks listed in this array, another may have 10. Using this structure, you will be able to easily display the correct number of tasks for each user in your Digest emails. More details on this below.\n\nThis nested structure works for both Contact-level as well as Global data points.\n\n**Example Request**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n\\t\\\"contacts\\\":[\\n\\t\\t{ \\n\\t\\t\\t\\\"name\\\":\\\"Tom\\\",\\n\\t\\t\\t\\\"email\\\":\\\"tom@test.com\\\",\\n\\t\\t\\t\\\"data\\\":{\\n\\t\\t\\t\\t\\\"tasks\\\":[\\n\\t\\t\\t\\t\\t{ \\\"name\\\":\\\"Get milk\\\",\\\"status\\\":\\\"incomplete\\\" },\\n\\t\\t\\t\\t\\t{ \\\"name\\\":\\\"Walk the dog\\\",\\\"status\\\":\\\"incomplete\\\" },\\n\\t\\t\\t\\t\\t{ \\\"name\\\":\\\"Buy beer\\\",\\\"type\\\":\\\"done\\\" }\\n\\t\\t\\t\\t]\\n\\t\\t\\t}\\n\\t\\t},\\n\\t\\t{ \\n\\t\\t\\t\\\"name\\\":\\\"Sarah\\\",\\n\\t\\t\\t\\\"email\\\":\\\"sarah@test.com\\\",\\n\\t\\t\\t\\\"data\\\":{\\n\\t\\t\\t\\t\\\"tasks\\\":[\\n\\t\\t\\t\\t\\t{ \\\"name\\\":\\\"Walk the dog\\\",\\\"status\\\":\\\"incomplete\\\" },\\n\\t\\t\\t\\t\\t{ \\\"name\\\":\\\"Get mail\\\",\\\"type\\\":\\\"done\\\" }\\n\\t\\t\\t\\t]\\n\\t\\t\\t}\\n\\t\\t}\\n\\t]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nAs mentioned above, using these nested data structures give you the ability to create sections in your emails that repeat as many times as their are 'children' in the structure. For example, some of your users will have 10 tasks, some will have 4 and others will have none. \n\nWhen you insert a 'child' element from any nested structure into a section in the Knowtify email editor (as indicated with a {parent.child} structure), that section will repeat itself for as many 'children' as there are for that specific user.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/DfHjq93DR125BHA7Nw6m_skitch.png\",\n        \"skitch.png\",\n        \"538\",\n        \"276\",\n        \"#2f4690\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"DATA TYPES & FORMATS\"\n}\n[/block]\nKnowtify supports various types of data that can be used to segment your messages or as content to insert into your messages. These data types can be managed on the Data tab of your account.\n\nThe data types we support include:\n\n- Strings\n- Numbers\n- Dates\n- Enumerated (coming soon)\n- [Nested](http://api.knowtify.io/docs/nested-data-structrues) \n\nEach one of these different data-types drive different logic in the Knowtify rule setting engine. \n\nKnowtify automatically assigns each piece of data a Type upon receiving it. If you would ever like to change the data type for any one of your keys, you can do so on the Data tab of your account.\n\n##Dates\n\nWhen you ship over Dates as data points, you will be able to use the following operators in your segmentation:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/aMV6gtADQe6WCxJOHYcr_skitch.png\",\n        \"skitch.png\",\n        \"534\",\n        \"284\",\n        \"#406491\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n*=*:               Equals. Use this to target a specific date. You must use the proper format (see below)\n*&#x2260;*:           Does not equal (see proper format)\n**>**:                  Greater than. This is to specify any date AFTER a specific date (see proper format)\n**<**:                   Less than. This is to specify any date BEFORE a specific date (see proper format)\n**days ago**:       An exact number of days since that date.\n**greater than days ago**:      This will segment contacts who's activity took place X days more than the date in this data point.\n**less than days ago**:          This will segment contacts who's activity took place X days less than the date in this data point.\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"ACCEPTED FORMAT FOR DATES\",\n  \"body\": \"In order to use dates in Knowtify, they have to be formatted one of two ways:\\n\\nyyyy-mm-dd\\n\\nOR\\n\\nyyyy-mm-dd hh:mm:ss\\n\\nIf you do not use one of these formats, you will not be able properly segment contacts or set rules based on this value in Knowtify.\"\n}\n[/block]","slug":"knowtify-rest-api","title":"Knowtify REST API"}

Knowtify REST API


Just a quick overview of integrating with the Knowtify API. Want a quick way to test our API? Check out our [Postman collection](http://api.knowtify.io/v1.0/docs/postman). [block:api-header] { "type": "basic", "title": "What is the Knowtify API?" } [/block] Unless you are interacting with Knowtify via one of our integration partners, our API will be the main way your app will talk to our platform. In this case, you will use our API to send Knowtify all the data and information you need to build and manage your different email initiatives: - For [Transactional emails](http://api.knowtify.io/docs/sending-event-based-emails), you will use our API to send event data to Knowtify as well as to trigger the email to be delivered. - For Behavioral emails, you will use our API to send behavioral data about your users. You should ship any data or information that you would want to use to define if and when a user should receive one of your behavioral emails. - For Digest emails, you will use our API to send over the data that will populate your digest emails as well as any data that will help you segment the recipient of the email and/or the sections within the email. It is typical that your app will ship data to Knowtify via our API 1-2 hours before any of your Digests are scheduled to go out. [block:api-header] { "type": "basic", "title": "How does the Knowtify API work?" } [/block] We currently only offer a JSON API using token authentication. If that doesn't make sense to you, please send this to your tech team. If you are the tech team and it still doesn't make sense, please email us at success@knowtify.io and we'll help you get going. [block:callout] { "type": "info", "body": "You can find your API token on the[ Account page](http://www.knowtify.io/settings) of your Knowtify account.", "title": "Your API Token" } [/block] [block:api-header] { "type": "basic", "title": "Request Header" } [/block] When making a request, you will need to add the following to the request header. [block:code] { "codes": [ { "code": "Authorization: Token token=\"API_TOKEN\"\nContent-Type: application/json", "language": "text" } ] } [/block] [block:api-header] { "type": "basic", "title": "Base URL" } [/block] [block:code] { "codes": [ { "code": "http://www.knowtify.io/api/v1", "language": "text" } ] } [/block] [block:api-header] { "type": "basic", "title": "Adding Contacts & Contact-Level Data" } [/block] [block:code] { "codes": [ { "code": "POST /contacts/upsert", "language": "text" } ] } [/block] You can Add, Update and/or Edit any contact and his/her data with a simple UPSERT call. When you post contacts using the UPSERT can Knowtify recognizes the email address of the contact, it will edit the data attached to that contact. If Knowtify doesn't recognize the email address of the contact, it will ADD a new contact. You will get a response back with the status of your request. **Example request:** [block:code] { "codes": [ { "code": "{\n \"contacts\": [\n {\n \"name\":\"John\",\n \"email\":\"john@test.com\",\n \"data\":{\n \"category\":\"sports\",\n \"followers\":300\t\n }\n },\n {\n \"name\":\"Samuel\",\n \"email\":\"sam@test.com\",\n \"data\":{\n \"category\":\"sports\",\n \"followers\":32,\n \"comments\":54,\n \"role\":\"Editor\"\n }\n }\n ]\n}", "language": "json" } ] } [/block] [block:api-header] { "type": "basic", "title": "Delete Contacts" } [/block] [block:code] { "codes": [ { "code": "POST /contacts/delete", "language": "text" } ] } [/block] Batch deletes require the **"contacts"** array to be strings of emails to be deleted. If you accidentally send an add/edit/upsert request to the delete endpoint, an error will be thrown and the contacts will be preserved because of the formatting requirements. **Example Request** [block:code] { "codes": [ { "code": "{\n \"contacts\": [\n \"john@test.com\",\n \"sam@test.com\",\n \"sarah@test.com\",\n \"mike@test.com\",\n \"jill@test.com\",\n \"ashley@test.com\",\n \"frank@test.com\",\n \"bill@test.com\"\n ]\n}", "language": "json" } ] } [/block] [block:api-header] { "type": "basic", "title": "Edit Global Data" } [/block] [block:code] { "codes": [ { "code": "POST /data/edit", "language": "text" } ] } [/block] [Global data](http://api.knowtify.io/v1.0/docs/getting-started#two-types-of-data-in-knowtify) can be used in digest blocks by using double curly braces - **{{users}}** When editing global data send only the key/value pairs you want to change. **Example Request** [block:code] { "codes": [ { "code": "{\n \"data\": {\n \"users\":890,\n \"comments\":994,\n \"top_story_url\":\"test.com/story\",\n \"top_story_title\":\"Article!\"\n }\n}", "language": "json" } ] } [/block] [block:api-header] { "type": "basic", "title": "Incrementing Data Points" } [/block] Sometimes you just want to be able to increment or decrement one of your global or contact data points without persisting data and running simple computations on your server. Good news! Now you can make a regular API request to /data/edit or /contacts/upsert using either "+1" or "-1" as a data point value and we'll do the math on our end. ##Global Data Example [block:code] { "codes": [ { "code": "{\n \"data\":{\n \"total_apps_built\":\"+1\",\n \"days_to_launch\":\"-1\"\n }\n}", "language": "json" } ] } [/block] ##Contact Data Example [block:code] { "codes": [ { "code": "{\n \"contacts\": [\n {\n \"email\":\"contact@test.com\",\n \"data\":{\n \"downloads\":\"+1\",\n \t\"friends_invited\":\"+1\"\n }\n }\n \t]\n}", "language": "json" } ] } [/block] [block:api-header] { "type": "basic", "title": "CONTENT LOOPS & NESTED DATA" } [/block] An overview of using more complex data structures See our [Postman collection](http://api.knowtify.io/v1.0/docs/postman). Nested data structures will be essential for many of your Digest emails. These nested structures allow you to create more flexible sections in your emails - in the case each user/recipient of your emails have a variable number of some element you want to display in your Digest. For example, each one of your users may have a different number of Tasks due for the day, each Task having sub-data attached (Name of Task, Type of Task, Due Date, etc). In this case Tasks would be the parent data point and each element of that task would represent sub-data points (or "children"). One of your users may have 3 tasks listed in this array, another may have 10. Using this structure, you will be able to easily display the correct number of tasks for each user in your Digest emails. More details on this below. This nested structure works for both Contact-level as well as Global data points. **Example Request** [block:code] { "codes": [ { "code": "{\n\t\"contacts\":[\n\t\t{ \n\t\t\t\"name\":\"Tom\",\n\t\t\t\"email\":\"tom@test.com\",\n\t\t\t\"data\":{\n\t\t\t\t\"tasks\":[\n\t\t\t\t\t{ \"name\":\"Get milk\",\"status\":\"incomplete\" },\n\t\t\t\t\t{ \"name\":\"Walk the dog\",\"status\":\"incomplete\" },\n\t\t\t\t\t{ \"name\":\"Buy beer\",\"type\":\"done\" }\n\t\t\t\t]\n\t\t\t}\n\t\t},\n\t\t{ \n\t\t\t\"name\":\"Sarah\",\n\t\t\t\"email\":\"sarah@test.com\",\n\t\t\t\"data\":{\n\t\t\t\t\"tasks\":[\n\t\t\t\t\t{ \"name\":\"Walk the dog\",\"status\":\"incomplete\" },\n\t\t\t\t\t{ \"name\":\"Get mail\",\"type\":\"done\" }\n\t\t\t\t]\n\t\t\t}\n\t\t}\n\t]\n}", "language": "json" } ] } [/block] As mentioned above, using these nested data structures give you the ability to create sections in your emails that repeat as many times as their are 'children' in the structure. For example, some of your users will have 10 tasks, some will have 4 and others will have none. When you insert a 'child' element from any nested structure into a section in the Knowtify email editor (as indicated with a {parent.child} structure), that section will repeat itself for as many 'children' as there are for that specific user. [block:image] { "images": [ { "image": [ "https://files.readme.io/DfHjq93DR125BHA7Nw6m_skitch.png", "skitch.png", "538", "276", "#2f4690", "" ] } ] } [/block] [block:api-header] { "type": "basic", "title": "DATA TYPES & FORMATS" } [/block] Knowtify supports various types of data that can be used to segment your messages or as content to insert into your messages. These data types can be managed on the Data tab of your account. The data types we support include: - Strings - Numbers - Dates - Enumerated (coming soon) - [Nested](http://api.knowtify.io/docs/nested-data-structrues) Each one of these different data-types drive different logic in the Knowtify rule setting engine. Knowtify automatically assigns each piece of data a Type upon receiving it. If you would ever like to change the data type for any one of your keys, you can do so on the Data tab of your account. ##Dates When you ship over Dates as data points, you will be able to use the following operators in your segmentation: [block:image] { "images": [ { "image": [ "https://files.readme.io/aMV6gtADQe6WCxJOHYcr_skitch.png", "skitch.png", "534", "284", "#406491", "" ] } ] } [/block] *=*: Equals. Use this to target a specific date. You must use the proper format (see below) *&#x2260;*: Does not equal (see proper format) **>**: Greater than. This is to specify any date AFTER a specific date (see proper format) **<**: Less than. This is to specify any date BEFORE a specific date (see proper format) **days ago**: An exact number of days since that date. **greater than days ago**: This will segment contacts who's activity took place X days more than the date in this data point. **less than days ago**: This will segment contacts who's activity took place X days less than the date in this data point. [block:callout] { "type": "danger", "title": "ACCEPTED FORMAT FOR DATES", "body": "In order to use dates in Knowtify, they have to be formatted one of two ways:\n\nyyyy-mm-dd\n\nOR\n\nyyyy-mm-dd hh:mm:ss\n\nIf you do not use one of these formats, you will not be able properly segment contacts or set rules based on this value in Knowtify." } [/block]