{"_id":"54211ad2f980dee664db9fc5","category":{"_id":"53844558a43e08da4677be13","pages":["53844558a43e08da4677be14","54211ad2f980dee664db9fc5","54212689f980dee664db9fc9","5421d851f980dee664db9ffe","54504d643c6f700800a9b4de","548f7589a8f6730b004b34b3","554a9af6b4322819002b6a1b","55a44d8b1fd6fb0d00d6fb2a"],"project":"53844557a43e08da4677be0e","version":"53844558a43e08da4677be12","__v":14,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-05-27T07:57:12.144Z","from_sync":false,"order":0,"slug":"general-api-documentation","title":"General API Documentation"},"is_link":false,"version":{"_id":"53844558a43e08da4677be12","__v":8,"project":"53844557a43e08da4677be0e","createdAt":"2014-05-27T07:57:12.136Z","releaseDate":"2014-05-27T07:57:12.136Z","categories":["53844558a43e08da4677be13","538619e1ef91f96d49aa1a0b","541e82877eb16bb64f83c0ca","5445a073c3eb3808000c76b2","5445a098c3eb3808000c76b3","54bb05ab522f03150054d9e8","54bb05cf9741c81500078f73","55b7d0e5568be2230092bb92"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"false","version_clean":"1.0.0","version":"1.0"},"__v":15,"user":"5384345d90c19d5e43a8170c","project":"53844557a43e08da4677be0e","updates":[],"next":{"pages":[],"description":""},"createdAt":"2014-09-23T07:01:38.751Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"basic_auth":false,"results":{"codes":[]},"settings":"","try":true,"auth":"never","params":[],"url":""},"isReference":false,"order":1,"body":"[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, 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:::at:::knowtify.io and we'll help you get going.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Your API Token\",\n  \"body\": \"You can find your API token on the[ Account page](http://www.knowtify.io/settings) of your Knowtify account.\"\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\": \"Fetching Contacts\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"GET /contacts?offset=0&count=500\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nYou'll need to provide an offset and a count when making a fetch request. This will allow you to get back data in batches in case you've got too many contacts to return in a single request.\n\n** Example: **\nSo if you've got 2,000 contacts and want to get everything in 2 requests you could make the following requests.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"GET /contacts?offset=0&count=1000\\nGET /contacts?offset=1000&count=1000\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nIf the request is timing out, that means your batches are too big. Cut the count in half and try again. The ideal batch size depends on how fast you want to process requests and how much data you have per contact. In general 500-1000 contacts is a reasonable batch size. \n\n**Example Response:**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"total_contacts\\\": 500,\\n  \\\"fetch_offset\\\": 0,\\n  \\\"fetch_count\\\": 2,\\n  \\\"contacts\\\": [\\n    {\\n      \\\"email\\\": \\\"joe@test.com\\\",\\n      \\\"name\\\": \\\"Joe\\\",\\n      \\\"data\\\": {\\n        \\\"name\\\": \\\"Joe\\\",\\n        \\\"email\\\": \\\"joe@test.com\\\",\\n        \\\"id\\\": \\\"12345\\\",\\n        \\\"friends\\\": 10\\n      }\\n    },\\n    {\\n      \\\"email\\\": \\\"jane@test.com\\\",\\n      \\\"name\\\": \\\"Jane\\\",\\n      \\\"data\\\": {\\n        \\\"name\\\": \\\"Jane\\\",\\n        \\\"email\\\": \\\"jane@test.com\\\",\\n        \\\"id\\\": \\\"123\\\",\\n        \\\"friends\\\": 25\\n      }\\n    }\\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]","excerpt":"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).","slug":"knowtify-api-basics","type":"basic","title":"KNOWTIFY API BASICS"}

KNOWTIFY API BASICS

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, 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", "title": "Your API Token", "body": "You can find your API token on the[ Account page](http://www.knowtify.io/settings) of your Knowtify account." } [/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": "Fetching Contacts" } [/block] [block:code] { "codes": [ { "code": "GET /contacts?offset=0&count=500", "language": "text" } ] } [/block] You'll need to provide an offset and a count when making a fetch request. This will allow you to get back data in batches in case you've got too many contacts to return in a single request. ** Example: ** So if you've got 2,000 contacts and want to get everything in 2 requests you could make the following requests. [block:code] { "codes": [ { "code": "GET /contacts?offset=0&count=1000\nGET /contacts?offset=1000&count=1000", "language": "text" } ] } [/block] If the request is timing out, that means your batches are too big. Cut the count in half and try again. The ideal batch size depends on how fast you want to process requests and how much data you have per contact. In general 500-1000 contacts is a reasonable batch size. **Example Response:** [block:code] { "codes": [ { "code": "{\n \"total_contacts\": 500,\n \"fetch_offset\": 0,\n \"fetch_count\": 2,\n \"contacts\": [\n {\n \"email\": \"joe@test.com\",\n \"name\": \"Joe\",\n \"data\": {\n \"name\": \"Joe\",\n \"email\": \"joe@test.com\",\n \"id\": \"12345\",\n \"friends\": 10\n }\n },\n {\n \"email\": \"jane@test.com\",\n \"name\": \"Jane\",\n \"data\": {\n \"name\": \"Jane\",\n \"email\": \"jane@test.com\",\n \"id\": \"123\",\n \"friends\": 25\n }\n }\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]