{"_id":"5a305118c8392b0032f6ae18","category":{"_id":"5a305118c8392b0032f6ae09","version":"5a305118c8392b0032f6ae07","project":"5425e663ffd4411c319a65b4","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-09-29T20:18:57.785Z","from_sync":false,"order":1,"slug":"reference","title":"Reference"},"user":"5425e31affd4411c319a65b1","project":"5425e663ffd4411c319a65b4","version":{"_id":"5a305118c8392b0032f6ae07","project":"5425e663ffd4411c319a65b4","__v":1,"createdAt":"2017-12-12T21:58:48.080Z","releaseDate":"2017-12-12T21:58:48.080Z","categories":["5a305118c8392b0032f6ae08","5a305118c8392b0032f6ae09"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"2.6.0","version":"2.6"},"githubsync":"","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2014-09-30T20:44:06.142Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"never","params":[],"url":""},"isReference":false,"order":6,"body":"A recipient is an organization’s customer and a target for a task, that is, whom the task is being delivered to.\n[block:api-header]\n{\n  \"type\": \"post\",\n  \"title\": \"Create recipient\"\n}\n[/block]\nBody parameters\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"name\",\n    \"0-1\": \"string\",\n    \"0-2\": \"The recipient’s complete name.\",\n    \"1-0\": \"phone\",\n    \"1-1\": \"string\",\n    \"1-2\": \"A unique, valid phone number as per the recipient’s organization’s ```country```.\",\n    \"2-0\": \"notes\",\n    \"2-1\": \"string\",\n    \"2-2\": \"Optional. Notes for this recipient: these are global notes that should not be task- or destination-specific. For example, *\\\"Customer since June 2012, does not drink non-specialty coffee\\\"*.\",\n    \"3-0\": \"skipSMSNotifications\",\n    \"3-1\": \"boolean\",\n    \"3-2\": \"Optional. Whether this recipient has requested to not receive SMS notifications. Defaults to ```false``` if not provided.\",\n    \"4-0\": \"skipPhoneNumberValidation\",\n    \"4-1\": \"boolean\",\n    \"4-2\": \"Optional. Whether to skip validation of this recipient's  phone number. An E.164-like number is still required (must start with `+`), however the API will not enforce any country-specific validation rules.\"\n  },\n  \"cols\": 3,\n  \"rows\": 5\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$ curl -X POST \\\"https://onfleet.com/api/v2/recipients\\\" \\\\\\n       -u \\\"cd3b3de84cc1ee040bf06512d233719c:\\\" \\\\\\n       -d '{\\\"name\\\":\\\"Boris Foster\\\",\\\"phone\\\":\\\"650-555-1133\\\",\\\"notes\\\":\\\"Always orders our GSC special\\\"}'\",\n      \"language\": \"shell\",\n      \"name\": \"Request\"\n    },\n    {\n      \"code\": \"$ curl -X POST \\\"https://onfleet.com/api/v2/recipients\\\" \\\\\\n       -u \\\"cd3b3de84cc1ee040bf06512d233719c:\\\" \\\\\\n       -d '{\\\"name\\\":\\\"Boris Foster\\\",\\\"phone\\\":\\\"+1111111111\\\",\\\"notes\\\":\\\"Always orders our GSC special\\\", \\\"skipPhoneNumberValidation\\\":\\\"true\\\"}'\",\n      \"language\": \"curl\",\n      \"name\": \"Request - Skip Phone Validation\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"id\\\": \\\"VVLx5OdKvw0dRSjT2rGOc6Y*\\\",\\n  \\\"organization\\\": \\\"yAM*fDkztrT3gUcz9mNDgNOL\\\",\\n  \\\"timeCreated\\\": 1455156665000,\\n  \\\"timeLastModified\\\": 1455156665390,\\n  \\\"name\\\": \\\"Boris Foster\\\",\\n  \\\"phone\\\": \\\"+16505551133\\\",\\n  \\\"notes\\\": \\\"Always orders our GSC special\\\",\\n  \\\"skipSMSNotifications\\\": false,\\n  \\\"metadata\\\": []\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    },\n    {\n      \"code\": \"{\\n  \\\"code\\\": \\\"InvalidContent\\\",\\n  \\\"message\\\": {\\n    \\\"error\\\": 1000,\\n    \\\"message\\\": \\\"The values of one or more parameters are invalid.\\\",\\n    \\\"cause\\\": \\\"Invalid phone number.\\\",\\n    \\\"request\\\": \\\"ac7178da-daa5-43c5-9b4c-5bc759289e9f\\\"\\n  }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Error - Invalid Phone\"\n    }\n  ]\n}\n[/block]\nOnfleet utilizes Google's [phone number validation library](https://github.com/googlei18n/libphonenumber) to verify all phone numbers entered. Use ```skipPhoneNumberValidation``` in your HTTP request to skip validation.\n[block:api-header]\n{\n  \"type\": \"put\",\n  \"title\": \"Update recipient\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$ curl -X PUT \\\"https://onfleet.com/api/v2/recipients/VVLx5OdKvw0dRSjT2rGOc6Y*\\\" \\\\\\n       -u \\\"cd3b3de84cc1ee040bf06512d233719c:\\\" \\\\\\n       -d '{\\\"name\\\":\\\"Neiman Runtilly\\\"}'\",\n      \"language\": \"shell\",\n      \"name\": \"Request\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"id\\\": \\\"VVLx5OdKvw0dRSjT2rGOc6Y*\\\",\\n  \\\"organization\\\": \\\"yAM*fDkztrT3gUcz9mNDgNOL\\\",\\n  \\\"timeCreated\\\": 1455156665000,\\n  \\\"timeLastModified\\\": 1455156665741,\\n  \\\"name\\\": \\\"Neiman Runtilly\\\",\\n  \\\"phone\\\": \\\"+16505551133\\\",\\n  \\\"notes\\\": \\\"Always orders our GSC special\\\",\\n  \\\"skipSMSNotifications\\\": false,\\n  \\\"metadata\\\": []\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"get\",\n  \"title\": \"Find recipient\"\n}\n[/block]\nYou can search for recipients by ```name``` or ```phone```. Note that finding a recipient requires that there be an exact match for the target property provided. Names are case insensitive and must be properly encoded, while phones will be automatically E.164-formatted prior to performing the lookup as per your organization's ```country``` setting.\n\nTo find a recipient by name, the endpoint format is ```/name/:name```, for example, ```/name/jony%20chives```. Similarly, to find a recipient by phone, the format is ```/phone/:phone```, for example, ```/phone/4155521837```.\n\nIf the recipient was created without validation, you may provide the query parameter `skipPhoneNumberValidation` as `true` in order to bypass validation.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$ curl -X GET \\\"https://onfleet.com/api/v2/recipients/name/neiman%20runtilly\\\" \\\\\\n       -u \\\"cd3b3de84cc1ee040bf06512d233719c:\\\"\",\n      \"language\": \"shell\",\n      \"name\": \"Request\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"id\\\": \\\"7tuqrtwo75UlcJFCzDk7Clfk\\\",\\n  \\\"organization\\\": \\\"yAM*fDkztrT3gUcz9mNDgNOL\\\",\\n  \\\"timeCreated\\\": 1455142309000,\\n  \\\"timeLastModified\\\": 1455142309695,\\n  \\\"name\\\": \\\"Neiman Runtilly\\\",\\n  \\\"phone\\\": \\\"+16503201133\\\",\\n  \\\"notes\\\": \\\"Always orders our GSC special\\\",\\n  \\\"skipSMSNotifications\\\": false,\\n  \\\"metadata\\\": []\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"get\",\n  \"title\": \"Get single recipient\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$ curl -X GET \\\"https://onfleet.com/api/v2/recipients/VVLx5OdKvw0dRSjT2rGOc6Y*\\\" \\\\\\n       -u \\\"cd3b3de84cc1ee040bf06512d233719c:\\\"\",\n      \"language\": \"shell\",\n      \"name\": \"Request\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"id\\\": \\\"VVLx5OdKvw0dRSjT2rGOc6Y*\\\",\\n  \\\"organization\\\": \\\"yAM*fDkztrT3gUcz9mNDgNOL\\\",\\n  \\\"timeCreated\\\": 1455156665000,\\n  \\\"timeLastModified\\\": 1455156665741,\\n  \\\"name\\\": \\\"Neiman Runtilly\\\",\\n  \\\"phone\\\": \\\"+16505551133\\\",\\n  \\\"notes\\\": \\\"Always orders our GSC special\\\",\\n  \\\"skipSMSNotifications\\\": false,\\n  \\\"metadata\\\": []\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    },\n    {\n      \"code\": \"{\\n  \\\"code\\\": \\\"InvalidCredentials\\\",\\n  \\\"message\\\": {\\n    \\\"error\\\": 1103,\\n    \\\"message\\\": \\\"The resource requested is outside of the authenticated user's permissions scope.\\\",\\n    \\\"request\\\": \\\"77dc37e0-72b4-481e-80e8-2f39703c4716\\\"\\n  }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Error - Invalid Permission\"\n    },\n    {\n      \"code\": \"{\\n  \\\"code\\\": \\\"ResourceNotFound\\\",\\n  \\\"message\\\": {\\n    \\\"error\\\": 1402,\\n    \\\"message\\\": \\\"The requested resource does not exist.\\\",\\n    \\\"request\\\": \\\"f0d18f7d-ea66-4b15-b078-0b4283e2ff25\\\"\\n  }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Error - Resource Not Found\"\n    }\n  ]\n}\n[/block]\nWhen attempting to access a recipient endpoint that does not belong to your organization, an error message will be thrown stating that the request is outside of your permission scope.","excerpt":"","slug":"recipients","type":"basic","title":"Recipients"}
A recipient is an organization’s customer and a target for a task, that is, whom the task is being delivered to. [block:api-header] { "type": "post", "title": "Create recipient" } [/block] Body parameters [block:parameters] { "data": { "h-0": "Name", "h-1": "Type", "h-2": "Description", "0-0": "name", "0-1": "string", "0-2": "The recipient’s complete name.", "1-0": "phone", "1-1": "string", "1-2": "A unique, valid phone number as per the recipient’s organization’s ```country```.", "2-0": "notes", "2-1": "string", "2-2": "Optional. Notes for this recipient: these are global notes that should not be task- or destination-specific. For example, *\"Customer since June 2012, does not drink non-specialty coffee\"*.", "3-0": "skipSMSNotifications", "3-1": "boolean", "3-2": "Optional. Whether this recipient has requested to not receive SMS notifications. Defaults to ```false``` if not provided.", "4-0": "skipPhoneNumberValidation", "4-1": "boolean", "4-2": "Optional. Whether to skip validation of this recipient's phone number. An E.164-like number is still required (must start with `+`), however the API will not enforce any country-specific validation rules." }, "cols": 3, "rows": 5 } [/block] [block:code] { "codes": [ { "code": "$ curl -X POST \"https://onfleet.com/api/v2/recipients\" \\\n -u \"cd3b3de84cc1ee040bf06512d233719c:\" \\\n -d '{\"name\":\"Boris Foster\",\"phone\":\"650-555-1133\",\"notes\":\"Always orders our GSC special\"}'", "language": "shell", "name": "Request" }, { "code": "$ curl -X POST \"https://onfleet.com/api/v2/recipients\" \\\n -u \"cd3b3de84cc1ee040bf06512d233719c:\" \\\n -d '{\"name\":\"Boris Foster\",\"phone\":\"+1111111111\",\"notes\":\"Always orders our GSC special\", \"skipPhoneNumberValidation\":\"true\"}'", "language": "curl", "name": "Request - Skip Phone Validation" } ] } [/block] [block:code] { "codes": [ { "code": "{\n \"id\": \"VVLx5OdKvw0dRSjT2rGOc6Y*\",\n \"organization\": \"yAM*fDkztrT3gUcz9mNDgNOL\",\n \"timeCreated\": 1455156665000,\n \"timeLastModified\": 1455156665390,\n \"name\": \"Boris Foster\",\n \"phone\": \"+16505551133\",\n \"notes\": \"Always orders our GSC special\",\n \"skipSMSNotifications\": false,\n \"metadata\": []\n}", "language": "json", "name": "Response" }, { "code": "{\n \"code\": \"InvalidContent\",\n \"message\": {\n \"error\": 1000,\n \"message\": \"The values of one or more parameters are invalid.\",\n \"cause\": \"Invalid phone number.\",\n \"request\": \"ac7178da-daa5-43c5-9b4c-5bc759289e9f\"\n }\n}", "language": "json", "name": "Error - Invalid Phone" } ] } [/block] Onfleet utilizes Google's [phone number validation library](https://github.com/googlei18n/libphonenumber) to verify all phone numbers entered. Use ```skipPhoneNumberValidation``` in your HTTP request to skip validation. [block:api-header] { "type": "put", "title": "Update recipient" } [/block] [block:code] { "codes": [ { "code": "$ curl -X PUT \"https://onfleet.com/api/v2/recipients/VVLx5OdKvw0dRSjT2rGOc6Y*\" \\\n -u \"cd3b3de84cc1ee040bf06512d233719c:\" \\\n -d '{\"name\":\"Neiman Runtilly\"}'", "language": "shell", "name": "Request" } ] } [/block] [block:code] { "codes": [ { "code": "{\n \"id\": \"VVLx5OdKvw0dRSjT2rGOc6Y*\",\n \"organization\": \"yAM*fDkztrT3gUcz9mNDgNOL\",\n \"timeCreated\": 1455156665000,\n \"timeLastModified\": 1455156665741,\n \"name\": \"Neiman Runtilly\",\n \"phone\": \"+16505551133\",\n \"notes\": \"Always orders our GSC special\",\n \"skipSMSNotifications\": false,\n \"metadata\": []\n}", "language": "json", "name": "Response" } ] } [/block] [block:api-header] { "type": "get", "title": "Find recipient" } [/block] You can search for recipients by ```name``` or ```phone```. Note that finding a recipient requires that there be an exact match for the target property provided. Names are case insensitive and must be properly encoded, while phones will be automatically E.164-formatted prior to performing the lookup as per your organization's ```country``` setting. To find a recipient by name, the endpoint format is ```/name/:name```, for example, ```/name/jony%20chives```. Similarly, to find a recipient by phone, the format is ```/phone/:phone```, for example, ```/phone/4155521837```. If the recipient was created without validation, you may provide the query parameter `skipPhoneNumberValidation` as `true` in order to bypass validation. [block:code] { "codes": [ { "code": "$ curl -X GET \"https://onfleet.com/api/v2/recipients/name/neiman%20runtilly\" \\\n -u \"cd3b3de84cc1ee040bf06512d233719c:\"", "language": "shell", "name": "Request" } ] } [/block] [block:code] { "codes": [ { "code": "{\n \"id\": \"7tuqrtwo75UlcJFCzDk7Clfk\",\n \"organization\": \"yAM*fDkztrT3gUcz9mNDgNOL\",\n \"timeCreated\": 1455142309000,\n \"timeLastModified\": 1455142309695,\n \"name\": \"Neiman Runtilly\",\n \"phone\": \"+16503201133\",\n \"notes\": \"Always orders our GSC special\",\n \"skipSMSNotifications\": false,\n \"metadata\": []\n}", "language": "json", "name": "Response" } ] } [/block] [block:api-header] { "type": "get", "title": "Get single recipient" } [/block] [block:code] { "codes": [ { "code": "$ curl -X GET \"https://onfleet.com/api/v2/recipients/VVLx5OdKvw0dRSjT2rGOc6Y*\" \\\n -u \"cd3b3de84cc1ee040bf06512d233719c:\"", "language": "shell", "name": "Request" } ] } [/block] [block:code] { "codes": [ { "code": "{\n \"id\": \"VVLx5OdKvw0dRSjT2rGOc6Y*\",\n \"organization\": \"yAM*fDkztrT3gUcz9mNDgNOL\",\n \"timeCreated\": 1455156665000,\n \"timeLastModified\": 1455156665741,\n \"name\": \"Neiman Runtilly\",\n \"phone\": \"+16505551133\",\n \"notes\": \"Always orders our GSC special\",\n \"skipSMSNotifications\": false,\n \"metadata\": []\n}", "language": "json", "name": "Response" }, { "code": "{\n \"code\": \"InvalidCredentials\",\n \"message\": {\n \"error\": 1103,\n \"message\": \"The resource requested is outside of the authenticated user's permissions scope.\",\n \"request\": \"77dc37e0-72b4-481e-80e8-2f39703c4716\"\n }\n}", "language": "json", "name": "Error - Invalid Permission" }, { "code": "{\n \"code\": \"ResourceNotFound\",\n \"message\": {\n \"error\": 1402,\n \"message\": \"The requested resource does not exist.\",\n \"request\": \"f0d18f7d-ea66-4b15-b078-0b4283e2ff25\"\n }\n}", "language": "json", "name": "Error - Resource Not Found" } ] } [/block] When attempting to access a recipient endpoint that does not belong to your organization, an error message will be thrown stating that the request is outside of your permission scope.