{"_id":"57624356653c2d2200fec7c2","version":{"_id":"57624356653c2d2200fec79c","__v":20,"project":"55c8cff571d7580d0063a5e5","createdAt":"2016-06-16T06:12:38.244Z","releaseDate":"2016-06-16T06:12:38.244Z","categories":["57624356653c2d2200fec79d","57624356653c2d2200fec79e","57624356653c2d2200fec79f","57624356653c2d2200fec7a0","57624356653c2d2200fec7a1","57624356653c2d2200fec7a2","57624356653c2d2200fec7a3","57624356653c2d2200fec7a4","57624356653c2d2200fec7a5","57624356653c2d2200fec7a6","57624356653c2d2200fec7a7","57624356653c2d2200fec7a8","57624356653c2d2200fec7a9","57624356653c2d2200fec7aa","5779ca1b99b40b0e005abb3a","5779d198aea88b0e00f63277","5797d3ab17ced017003c4be4","57ac170ef1cdae0e0053cdfc","57dbfc723ed3450e00dc9e6d","5804d12d16161c0f0077df9b","5841064b652e5b0f0015a7c8","588b5e5f2966b2230009cbf9","58a68ebf3239fa0f00857619","58c23c8b4922930f0050ac91","58fd1460809fc30f00f2ee07","5934eaf5328680002d77de6a","594bf91601cfe6000f40f4c5","595c4ed696b447001ba0cf6d","596524495cee50001575f5be","5970d4f1313162004dd303b5","59780fac24dbd1001a1fa057","59a8cfd3ead78a002d63cafe","59e0323d93da1f001c9ec170"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"4.0.0","version":"4"},"category":{"_id":"57624356653c2d2200fec7a2","__v":0,"version":"57624356653c2d2200fec79c","project":"55c8cff571d7580d0063a5e5","sync":{"url":"","isSync":false},"reference":true,"createdAt":"2016-03-29T04:52:14.767Z","from_sync":false,"order":13,"slug":"account-extension-contacts","title":"Account Extension Contacts"},"parentDoc":null,"user":"55c8cf9471d7580d0063a5e4","__v":3,"project":"55c8cff571d7580d0063a5e5","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-29T19:13:36.174Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":true,"order":0,"body":"Each extension at Phone.com can have its own address book with any number of contacts. This page gives an overview.\n\n## Supported Services\n* [List Contacts](doc:list-account-extension-contacts) \n* [Create Contact](doc:create-account-extension-contact) \n* [Get Contact](doc:get-account-extension-contact) \n* [Replace Contact](doc:replace-account-extension-contact) \n* [Delete Contact](doc:delete-account-extension-contact) \n\n## Summary Object\nThe Contact Summary Object is used to briefly represent a contact from your address book. It can be seen in several places throughout this API. Here are the properties:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Property\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"`id`\",\n    \"0-1\": \"Integer ID. Read-only.\",\n    \"2-0\": \"`first_name`\",\n    \"2-1\": \"First name or given name\",\n    \"3-0\": \"`middle_name`\",\n    \"3-1\": \"Middle or second name\",\n    \"4-0\": \"`last_name`\",\n    \"4-1\": \"Last name or surname\",\n    \"6-0\": \"`nickname`\",\n    \"6-1\": \"Nickname, or a shortened informal version of the contact's name\",\n    \"7-0\": \"`company`\",\n    \"7-1\": \"Name of the contact's company\",\n    \"1-0\": \"`prefix`\",\n    \"1-1\": \"Salutation, such as `Mr`, `Mrs`, or `Dr`\",\n    \"5-0\": \"`suffix`\",\n    \"5-1\": \"Suffix, such as \\\"Jr.\\\", \\\"Sr.\\\", \\\"II\\\", or \\\"III\\\"\"\n  },\n  \"cols\": 2,\n  \"rows\": 8\n}\n[/block]\nHere is an example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"id\\\": 6753,\\n    \\\"prefix\\\": \\\"\\\",\\n    \\\"first_name\\\": \\\"Abraham\\\",\\n    \\\"middle_name\\\": \\\"\\\",\\n    \\\"last_name\\\": \\\"Lincoln\\\",\\n    \\\"nickname\\\": \\\"Old Abe\\\",\\n    \\\"company\\\": \\\"United States of America\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n## Full Object\nThe Full Contact Object includes all of the properties in the Contact Summary Object, along with several more:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Property\",\n    \"h-1\": \"Description\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"`phonetic_first_name`\",\n    \"0-1\": \"Phonetic first name. Useful for remembering how to pronounce the contact's name.\",\n    \"0-2\": \"\",\n    \"1-0\": \"`phonetic_middle_name`\",\n    \"1-1\": \"Phonetic middle name. Useful for remembering how to pronounce the contact's name.\",\n    \"1-2\": \"\",\n    \"2-0\": \"`phonetic_last_name`\",\n    \"2-1\": \"Phonetic last name. Useful for remembering how to pronounce the contact's name.\",\n    \"2-2\": \"\",\n    \"3-0\": \"`department`\",\n    \"3-1\": \"Name of the contact's department\",\n    \"3-2\": \"\",\n    \"4-0\": \"`job_title`\",\n    \"4-1\": \"Contact's job title\",\n    \"4-2\": \"\",\n    \"5-0\": \"`emails`\",\n    \"5-1\": \"Array of [Contact Email Objects](#section-email-objects). See below for details.\",\n    \"5-2\": \"\",\n    \"6-0\": \"`phone_numbers`\",\n    \"6-1\": \"Array of [Contact Phone Number Objects](#section-phone-number-objects). See below for details.\",\n    \"6-2\": \"\",\n    \"7-0\": \"`addresses`\",\n    \"7-1\": \"Array of [Contact Address Objects](#section-address-objects). See below for details.\",\n    \"7-2\": \"\",\n    \"8-0\": \"`group`\",\n    \"8-1\": \"[Contact Group](doc:account-extension-contact-groups) that this contact is filed under. Output is a [Group Summary Object](doc:account-extension-contact-groups#section-summary-object). Input is a [Group Lookup Object](doc:account-extension-contact-groups#section-lookup-object).\",\n    \"8-2\": \"\",\n    \"9-0\": \"`created_at`\",\n    \"9-1\": \"Integer UNIX timestamp when the contact was created. Read-only.\",\n    \"9-2\": \"\",\n    \"10-0\": \"`updated_at`\",\n    \"10-1\": \"Integer UNIX timestamp when the contact was created. Read-only.\",\n    \"10-2\": \"\"\n  },\n  \"cols\": 2,\n  \"rows\": 11\n}\n[/block]\nHere is an example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"id\\\": 4567352,\\n    \\\"prefix\\\": \\\"Captain\\\",\\n    \\\"first_name\\\": \\\"Jean-luc\\\",\\n    \\\"middle_name\\\": \\\"\\\",\\n    \\\"last_name\\\": \\\"Picard\\\",\\n    \\\"suffix\\\": \\\"\\\",\\n    \\\"nickname\\\": \\\"Captain Picard\\\",\\n    \\\"company\\\": \\\"United Federation of Planets\\\",\\n    \\\"phonetic_first_name\\\": \\\"\\\",\\n    \\\"phonetic_middle_name\\\": \\\"\\\",\\n    \\\"phonetic_last_name\\\": \\\"\\\",\\n    \\\"department\\\": \\\"Starfleet\\\",\\n    \\\"job_title\\\": \\\"Ship's Captain\\\",\\n    \\\"created_at\\\": 1459239422,\\n    \\\"updated_at\\\": 1459274344,\\n    \\\"emails\\\": [\\n        {\\n            \\\"type\\\": \\\"primary\\\",\\n            \\\"email\\\": \\\"jean-luc.picard:::at:::example.com\\\"\\n        }\\n    ],\\n    \\\"phone_numbers\\\": [\\n        {\\n            \\\"type\\\": \\\"business\\\",\\n            \\\"number\\\": \\\"(999) 999-9999\\\",\\n            \\\"normalized\\\": \\\"+19999999999\\\"\\n        }\\n    ],\\n    \\\"addresses\\\": [\\n        {\\n            \\\"type\\\": \\\"home\\\",\\n            \\\"street\\\": \\\"1212 Federation Way\\\",\\n            \\\"city\\\": \\\"San Francisco\\\",\\n            \\\"state\\\": \\\"CA\\\",\\n            \\\"zip\\\": \\\"99999\\\",\\n            \\\"country\\\": \\\"USA\\\"\\n        }\\n    ],\\n    \\\"group\\\": {\\n        \\\"id\\\": 982357,\\n        \\\"name\\\": \\\"NCC 1701-D Bridge Crew\\\"\\n    }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n## Email Objects\nEach entry in a contact's email list is an object with the following properties:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Property\",\n    \"h-1\": \"Description\",\n    \"h-2\": \"\",\n    \"0-0\": \"`type`\",\n    \"0-1\": \"Email type, one of: `primary` or `alternate`.  Default is `primary`.\",\n    \"0-2\": \"\",\n    \"1-0\": \"`email`\",\n    \"1-1\": \"Email address. Required.\",\n    \"1-2\": \"\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]\nNote that a contact can only have a maximum of two emails.\n\nHere is an example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"type\\\": \\\"primary\\\",\\n    \\\"email\\\": \\\"jean-luc.picard@example.com\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n##Phone Number Objects\nEach entry in a contact's phone number list is an object with the following properties:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Property\",\n    \"h-1\": \"Description\",\n    \"h-2\": \"\",\n    \"0-0\": \"`type`\",\n    \"0-1\": \"Type of phone number, must be one of: `home`, `business`, `mobile`, `fax`, `pager`. Default is `home`.\",\n    \"0-2\": \"\",\n    \"1-0\": \"`number`\",\n    \"1-1\": \"Phone number, as entered. Does not need to be formatted in any particular way if it is a USA phone number. For international number, use E.164 format. Required.\",\n    \"1-2\": \"\",\n    \"2-0\": \"`normalized`\",\n    \"2-1\": \"Phone number in E.164 format. Read-only.\",\n    \"2-2\": \"\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\nHere's an example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"type\\\": \\\"home\\\",\\n    \\\"number\\\": \\\"(999) 999-9999\\\",\\n    \\\"normalized\\\": \\\"+19999999999\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n## Address Objects\nEach entry in a contact's address list is an object with the following properties:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Property\",\n    \"h-1\": \"Description\",\n    \"h-2\": \"\",\n    \"0-0\": \"`type`\",\n    \"0-1\": \"Address type, one of: `home` or `business`. Default is `home`.\",\n    \"0-2\": \"\",\n    \"1-0\": \"`street`\",\n    \"1-1\": \"House number and street name, including apartment, suite, etc.\",\n    \"1-2\": \"\",\n    \"2-0\": \"`city`\",\n    \"2-1\": \"City\",\n    \"2-2\": \"\",\n    \"3-0\": \"`state`\",\n    \"3-1\": \"State or province\",\n    \"3-2\": \"\",\n    \"4-0\": \"`zip`\",\n    \"4-1\": \"Zip code or postal code\",\n    \"4-2\": \"\",\n    \"5-0\": \"`country`\",\n    \"5-1\": \"Country name\",\n    \"5-2\": \"\"\n  },\n  \"cols\": 3,\n  \"rows\": 6\n}\n[/block]\nHere's an example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"type\\\": \\\"home\\\",\\n    \\\"street\\\": \\\"1212 Federation Way\\\",\\n    \\\"city\\\": \\\"San Francisco\\\",\\n    \\\"state\\\": \\\"CA\\\",\\n    \\\"zip\\\": \\\"99999\\\",\\n    \\\"country\\\": \\\"USA\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n## Lookup Object\nThe Contact Lookup Object is used to link to a contact from another object. This is used, for example, when defining filters for [routes](doc:account-routes).  Only *one* of the following properties need to be included. If multiple are specified, then *all* properties must match one of your contacts.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Property\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"`id`\",\n    \"0-1\": \"ID\",\n    \"1-0\": \"`prefix`\",\n    \"1-1\": \"Prefix\",\n    \"2-0\": \"`first_name`\",\n    \"2-1\": \"First Name\",\n    \"3-0\": \"`middle_name`\",\n    \"3-1\": \"Middle Name\",\n    \"4-0\": \"`last_name`\",\n    \"4-1\": \"Last Name\",\n    \"5-0\": \"`suffix`\",\n    \"5-1\": \"Suffix\",\n    \"6-0\": \"`nickname`\",\n    \"6-1\": \"Nickname\",\n    \"7-0\": \"`company`\",\n    \"7-1\": \"Company\"\n  },\n  \"cols\": 2,\n  \"rows\": 8\n}\n[/block]\nHere are some examples:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"contact: {\\n    \\\"id\\\": 66352\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"contact: {\\n    \\\"first_name\\\": \\\"Will\\\",\\n    \\\"last_name\\\": \\\"Smith\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nInstead of inputting an object, you can also use a scalar value.  A contact will be found if the input matches any one of the above fields.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"contact: 66352\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"account-extension-contacts","type":"basic","title":"Contacts"}
Each extension at Phone.com can have its own address book with any number of contacts. This page gives an overview. ## Supported Services * [List Contacts](doc:list-account-extension-contacts) * [Create Contact](doc:create-account-extension-contact) * [Get Contact](doc:get-account-extension-contact) * [Replace Contact](doc:replace-account-extension-contact) * [Delete Contact](doc:delete-account-extension-contact) ## Summary Object The Contact Summary Object is used to briefly represent a contact from your address book. It can be seen in several places throughout this API. Here are the properties: [block:parameters] { "data": { "h-0": "Property", "h-1": "Description", "0-0": "`id`", "0-1": "Integer ID. Read-only.", "2-0": "`first_name`", "2-1": "First name or given name", "3-0": "`middle_name`", "3-1": "Middle or second name", "4-0": "`last_name`", "4-1": "Last name or surname", "6-0": "`nickname`", "6-1": "Nickname, or a shortened informal version of the contact's name", "7-0": "`company`", "7-1": "Name of the contact's company", "1-0": "`prefix`", "1-1": "Salutation, such as `Mr`, `Mrs`, or `Dr`", "5-0": "`suffix`", "5-1": "Suffix, such as \"Jr.\", \"Sr.\", \"II\", or \"III\"" }, "cols": 2, "rows": 8 } [/block] Here is an example: [block:code] { "codes": [ { "code": "{\n \"id\": 6753,\n \"prefix\": \"\",\n \"first_name\": \"Abraham\",\n \"middle_name\": \"\",\n \"last_name\": \"Lincoln\",\n \"nickname\": \"Old Abe\",\n \"company\": \"United States of America\"\n}", "language": "json" } ] } [/block] ## Full Object The Full Contact Object includes all of the properties in the Contact Summary Object, along with several more: [block:parameters] { "data": { "h-0": "Property", "h-1": "Description", "h-2": "Description", "0-0": "`phonetic_first_name`", "0-1": "Phonetic first name. Useful for remembering how to pronounce the contact's name.", "0-2": "", "1-0": "`phonetic_middle_name`", "1-1": "Phonetic middle name. Useful for remembering how to pronounce the contact's name.", "1-2": "", "2-0": "`phonetic_last_name`", "2-1": "Phonetic last name. Useful for remembering how to pronounce the contact's name.", "2-2": "", "3-0": "`department`", "3-1": "Name of the contact's department", "3-2": "", "4-0": "`job_title`", "4-1": "Contact's job title", "4-2": "", "5-0": "`emails`", "5-1": "Array of [Contact Email Objects](#section-email-objects). See below for details.", "5-2": "", "6-0": "`phone_numbers`", "6-1": "Array of [Contact Phone Number Objects](#section-phone-number-objects). See below for details.", "6-2": "", "7-0": "`addresses`", "7-1": "Array of [Contact Address Objects](#section-address-objects). See below for details.", "7-2": "", "8-0": "`group`", "8-1": "[Contact Group](doc:account-extension-contact-groups) that this contact is filed under. Output is a [Group Summary Object](doc:account-extension-contact-groups#section-summary-object). Input is a [Group Lookup Object](doc:account-extension-contact-groups#section-lookup-object).", "8-2": "", "9-0": "`created_at`", "9-1": "Integer UNIX timestamp when the contact was created. Read-only.", "9-2": "", "10-0": "`updated_at`", "10-1": "Integer UNIX timestamp when the contact was created. Read-only.", "10-2": "" }, "cols": 2, "rows": 11 } [/block] Here is an example: [block:code] { "codes": [ { "code": "{\n \"id\": 4567352,\n \"prefix\": \"Captain\",\n \"first_name\": \"Jean-luc\",\n \"middle_name\": \"\",\n \"last_name\": \"Picard\",\n \"suffix\": \"\",\n \"nickname\": \"Captain Picard\",\n \"company\": \"United Federation of Planets\",\n \"phonetic_first_name\": \"\",\n \"phonetic_middle_name\": \"\",\n \"phonetic_last_name\": \"\",\n \"department\": \"Starfleet\",\n \"job_title\": \"Ship's Captain\",\n \"created_at\": 1459239422,\n \"updated_at\": 1459274344,\n \"emails\": [\n {\n \"type\": \"primary\",\n \"email\": \"jean-luc.picard@example.com\"\n }\n ],\n \"phone_numbers\": [\n {\n \"type\": \"business\",\n \"number\": \"(999) 999-9999\",\n \"normalized\": \"+19999999999\"\n }\n ],\n \"addresses\": [\n {\n \"type\": \"home\",\n \"street\": \"1212 Federation Way\",\n \"city\": \"San Francisco\",\n \"state\": \"CA\",\n \"zip\": \"99999\",\n \"country\": \"USA\"\n }\n ],\n \"group\": {\n \"id\": 982357,\n \"name\": \"NCC 1701-D Bridge Crew\"\n }\n}", "language": "json" } ] } [/block] ## Email Objects Each entry in a contact's email list is an object with the following properties: [block:parameters] { "data": { "h-0": "Property", "h-1": "Description", "h-2": "", "0-0": "`type`", "0-1": "Email type, one of: `primary` or `alternate`. Default is `primary`.", "0-2": "", "1-0": "`email`", "1-1": "Email address. Required.", "1-2": "" }, "cols": 2, "rows": 2 } [/block] Note that a contact can only have a maximum of two emails. Here is an example: [block:code] { "codes": [ { "code": "{\n \"type\": \"primary\",\n \"email\": \"jean-luc.picard@example.com\"\n}", "language": "json" } ] } [/block] ##Phone Number Objects Each entry in a contact's phone number list is an object with the following properties: [block:parameters] { "data": { "h-0": "Property", "h-1": "Description", "h-2": "", "0-0": "`type`", "0-1": "Type of phone number, must be one of: `home`, `business`, `mobile`, `fax`, `pager`. Default is `home`.", "0-2": "", "1-0": "`number`", "1-1": "Phone number, as entered. Does not need to be formatted in any particular way if it is a USA phone number. For international number, use E.164 format. Required.", "1-2": "", "2-0": "`normalized`", "2-1": "Phone number in E.164 format. Read-only.", "2-2": "" }, "cols": 2, "rows": 3 } [/block] Here's an example: [block:code] { "codes": [ { "code": "{\n \"type\": \"home\",\n \"number\": \"(999) 999-9999\",\n \"normalized\": \"+19999999999\"\n}", "language": "json" } ] } [/block] ## Address Objects Each entry in a contact's address list is an object with the following properties: [block:parameters] { "data": { "h-0": "Property", "h-1": "Description", "h-2": "", "0-0": "`type`", "0-1": "Address type, one of: `home` or `business`. Default is `home`.", "0-2": "", "1-0": "`street`", "1-1": "House number and street name, including apartment, suite, etc.", "1-2": "", "2-0": "`city`", "2-1": "City", "2-2": "", "3-0": "`state`", "3-1": "State or province", "3-2": "", "4-0": "`zip`", "4-1": "Zip code or postal code", "4-2": "", "5-0": "`country`", "5-1": "Country name", "5-2": "" }, "cols": 3, "rows": 6 } [/block] Here's an example: [block:code] { "codes": [ { "code": "{\n \"type\": \"home\",\n \"street\": \"1212 Federation Way\",\n \"city\": \"San Francisco\",\n \"state\": \"CA\",\n \"zip\": \"99999\",\n \"country\": \"USA\"\n}", "language": "json" } ] } [/block] ## Lookup Object The Contact Lookup Object is used to link to a contact from another object. This is used, for example, when defining filters for [routes](doc:account-routes). Only *one* of the following properties need to be included. If multiple are specified, then *all* properties must match one of your contacts. [block:parameters] { "data": { "h-0": "Property", "h-1": "Description", "0-0": "`id`", "0-1": "ID", "1-0": "`prefix`", "1-1": "Prefix", "2-0": "`first_name`", "2-1": "First Name", "3-0": "`middle_name`", "3-1": "Middle Name", "4-0": "`last_name`", "4-1": "Last Name", "5-0": "`suffix`", "5-1": "Suffix", "6-0": "`nickname`", "6-1": "Nickname", "7-0": "`company`", "7-1": "Company" }, "cols": 2, "rows": 8 } [/block] Here are some examples: [block:code] { "codes": [ { "code": "contact: {\n \"id\": 66352\n}", "language": "json" } ] } [/block] [block:code] { "codes": [ { "code": "contact: {\n \"first_name\": \"Will\",\n \"last_name\": \"Smith\"\n}", "language": "json" } ] } [/block] Instead of inputting an object, you can also use a scalar value. A contact will be found if the input matches any one of the above fields. [block:code] { "codes": [ { "code": "contact: 66352", "language": "json" } ] } [/block]