--- title: "Create a contact" description: "POST /contacts — Creates a contact. Provide last_name or company_name — one of the two is required. owner_id defaults to the calling user and status_id to lead." canonical_url: https://developer.onepagecrm.com/api/reference/contacts/post-contacts/ source: Markdown mirror of https://developer.onepagecrm.com/api/reference/contacts/post-contacts/ --- `POST /contacts` Creates a contact. Provide last_name or company_name — one of the two is required. owner_id defaults to the calling user and status_id to lead. company_name links the contact to an existing company (matched case-insensitively) or creates one; company_id is ignored on create. Optional next_action_name (max 140 characters) creates the contact's first next action, with next_action_date set to asap, waiting or a YYYY-MM-DD date. Resource: [Contacts](https://developer.onepagecrm.com/api/reference/contacts/) · [API Reference](https://developer.onepagecrm.com/api/reference/) ## Request ```bash curl -X POST "https://app.onepagecrm.com/api/v3/contacts" \ -u $user_id:$api_key \ -H "Content-Type: application/json" \ -d '{ "title": "Mr", "first_name": "Joe", "last_name": "Bloggs", "job_title": "Engineer", "starred": true, "company_id": "5aba31ea9007ba0f570c92d5", "company_name": "Morgan's Forensic Lab", "urls": [ { "type": "linkedin", "value": "https://www.linkedin.com/{joe.bloggs}" } ], "phones": [ { "type": "work", "value": "(912) 644-1770" } ], "emails": [ { "type": "work", "value": "joe.bloggs@example.com" } ], "address_list": [ { "address": "Unit 5, Business Innovation Centre", "city": "Upper Newcastle", "state": "Galway", "zip_code": "H91 Y0T0", "country_code": "IE", "type": "delivery" } ], "status_id": "5e31e030849d781e837b6ba1", "tags": [ "Java", "Android", "iOS" ], "lead_source_id": "advertisement", "background": "I met Joe Bloggs at the annual Eco Conference in Florida. Her company currently provides solar panels (along with a lot of other stuff) to the State Government of California, Nevada, Oregon, Arizona and Utah for capital building projects. Her current supplier is crazy expensive! I've asked to be able to tender for their next order.", "owner_id": "5aba31e99007ba0f570c92a5", "custom_fields": [ { "custom_field": { "id": "5aad9b039007ba28c9ebad56" }, "value": "Large" } ] }' ``` Authentication is HTTP Basic — `user_id` as username, `api_key` as password. See https://developer.onepagecrm.com/api/authentication/. ## Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `title` | string | | The title of the contact | | `first_name` | string | | First name of the contact | | `last_name` | string | | Last name of the contact | | `job_title` | string | | Job title of the contact | | `starred` | boolean | | Is the contact starred? | | `company_id` | string (bson-id) | | ID of the company, to which the contact belongs | | `company_name` | string | | Name of the company, to whom the contact belongs | | `urls` | array | | URLs associated with the contact | | `phones` | array | | Phone numbers associated with the contact | | `emails` | array | | Email addresses associated with the contact | | `address_list` | array | | An array of contact addresses. | | `status_id` | string (bson-id) | | ID of the status of the contact | | `tags` | array | | Tags on the contact — free-form strings from the account's tag list. | | `lead_source_id` | string | | ID of the lead source | | `background` | string | | Background infomation about the contact | | `owner_id` | string (bson-id) | | ID of the user, to whom the contact belongs. Defaults to the logged API user's ID. | | `custom_fields` | array | | Extra user-configurable data fields for Contacts. Only editable by admins. | ## Responses ### 201 Created ```json { "status": 0, "message": "OK", "timestamp": 1528373119, "data": { "contact": { "id": "5aba31ea9007ba0f570c92d4", "title": "Mr", "first_name": "Joe", "last_name": "Bloggs", "job_title": "Engineer", "starred": true, "photo_url": "https://{foo.bar}/joe-bloggs.jpg", "company_id": "5aba31ea9007ba0f570c92d5", "company_name": "Morgan's Forensic Lab", "urls": [ { "type": "linkedin", "value": "https://www.linkedin.com/{joe.bloggs}" } ], "phones": [ { "type": "work", "value": "(912) 644-1770" } ], "emails": [ { "type": "work", "value": "joe.bloggs@example.com" } ], "address_list": [ { "address": "Unit 5, Business Innovation Centre", "city": "Upper Newcastle", "state": "Galway", "zip_code": "H91 Y0T0", "country_code": "IE", "type": "delivery" } ], "status": "Prospect", "status_id": "5e31e030849d781e837b6ba1", "tags": [ "Java", "Android", "iOS" ], "lead_source_id": "email_web", "lead_source": "Email or Web", "background": "I met Joe Bloggs at the annual Eco Conference in Florida. Her company currently provides solar panels (along with a lot of other stuff) to the State Government of California, Nevada, Oregon, Arizona and Utah for capital building projects. Her current supplier is crazy expensive! I've asked to be able to tender for their next order.", "owner_id": "5aba31e99007ba0f570c92a5", "custom_fields": [ { "custom_field": { "id": "5aad9b039007ba18c9ebad13", "name": "Favorite season", "type": "select_box", "position": 2, "choices": [ "Spring", "Summer", "Autumn", "Winter" ] }, "value": "Summer" } ], "letter": "b", "pending_deal": true, "total_pendings": 999.99, "total_deals_count": 3, "company_size": 1, "sales_closed_for": [ "5aba31e99007ba0f570c12f7" ], "closed_sales": [ { "user_id": "5aba31e99007ba0f570c12f7", "closed_at": 1524818902, "comment": "Client is no longer interested" } ], "google_contacts_data": { "account_email": "jane.doe@example.com", "id": "342c5b5c08d4b0b2", "saved_at": 1522840153 }, "created_at": "2018-05-16T11:52:09Z", "modified_at": "2018-05-16T11:52:09Z" }, "next_actions": [ { "id": "5aeac8789007ba56ffca92b9", "assignee_id": "5aaa9b009007ba08c9ebaef7", "contact_id": "5aba31ea9007ba0f570c92d4", "text": "#1 Email Jane introducing our organization", "status": "date_time", "date": "2018-05-16", "exact_time": 1526472000, "position": 1, "done": false, "done_at": "2018-05-16", "created_at": "2018-05-16T11:52:09Z", "modified_at": "2018-05-16T12:52:09Z" } ], "next_action": { "id": "5aeac8789007ba56ffca92b9", "assignee_id": "5aaa9b009007ba08c9ebaef7", "contact_id": "5aba31ea9007ba0f570c92d4", "text": "#1 Email Jane introducing our organization", "status": "date_time", "date": "2018-05-16", "exact_time": 1526472000, "position": 1, "done": false, "done_at": "2018-05-16", "created_at": "2018-05-16T11:52:09Z", "modified_at": "2018-05-16T12:52:09Z" }, "queued_actions": [ { "id": "5aeac8789007ba56ffca92b9", "assignee_id": "5aaa9b009007ba08c9ebaef7", "contact_id": "5aba31ea9007ba0f570c92d4", "text": "#1 Email Jane introducing our organization", "status": "date_time", "date": "2018-05-16", "exact_time": 1526472000, "position": 1, "done": false, "done_at": "2018-05-16", "created_at": "2018-05-16T11:52:09Z", "modified_at": "2018-05-16T12:52:09Z" } ], "next_action_conflicts": [], "company": { "id": "5aba31e99007ba0f570c92ac", "image": "data:image/png;base64,iVBORw...", "name": "Crockett & Tubbs Security", "description": "For all your security needs", "phone": "(912) 644-1771", "photo_url": "https://example.com/someimage.png", "url": "https://{foo.bar}", "address": { "address": "Unit 5, Business Innovation Centre", "city": "Upper Newcastle", "state": "Galway", "zip_code": "H91 Y0T0", "country_code": "IE" }, "company_fields": [ { "company_field": { "id": "5aad9b039007ba28c9ebad56", "name": "Company size", "type": "select_box", "position": 2, "choices": [ "Small", "Medium", "Large" ] }, "value": "Large" } ], "syncing_status": true, "synced_status_id": "5aaa9b039007ba08c9ebaf0a", "syncing_tags": true, "synced_tags": [ "Java", "Android", "iOS" ], "contacts_count": 3, "won_deals_count": 5, "total_won_amount": 999.99, "pending_deals_count": 1, "total_pending_amount": 99.99, "contacts": [ { "contact": { "id": "5aba31ea9007ba0f570c92d4", "title": "Mr", "first_name": "Joe", "last_name": "Bloggs", "job_title": "Engineer", "starred": true, "photo_url": "https://{foo.bar}/joe-bloggs.jpg", "company_id": "5aba31ea9007ba0f570c92d5", "company_name": "Morgan's Forensic Lab", "urls": [], "phones": [], "emails": [], "address_list": [], "status": "Prospect", "status_id": "5e31e030849d781e837b6ba1", "tags": [ "Java", "Android", "iOS" ], "lead_source_id": "email_web", "lead_source": "Email or Web", "background": "I met Joe Bloggs at the annual Eco Conference in Florida. Her company currently provides solar panels (along with a lot of other stuff) to the State Government of California, Nevada, Oregon, Arizona and Utah for capital building projects. Her current supplier is crazy expensive! I've asked to be able to tender for their next order.", "owner_id": "5aba31e99007ba0f570c92a5", "custom_fields": [], "letter": "b", "pending_deal": true, "total_pendings": 999.99, "total_deals_count": 3, "company_size": 1, "sales_closed_for": [ "5aba31e99007ba0f570c12f7" ], "closed_sales": [], "google_contacts_data": {}, "created_at": "2018-05-16T11:52:09Z", "modified_at": "2018-05-16T11:52:09Z" }, "next_actions": [ {} ], "next_action": { "id": "5aeac8789007ba56ffca92b9", "assignee_id": "5aaa9b009007ba08c9ebaef7", "contact_id": "5aba31ea9007ba0f570c92d4", "text": "#1 Email Jane introducing our organization", "status": "date_time", "date": "2018-05-16", "exact_time": 1526472000, "position": 1, "done": false, "done_at": "2018-05-16", "created_at": "2018-05-16T11:52:09Z", "modified_at": "2018-05-16T12:52:09Z" }, "queued_actions": [ {} ], "next_action_conflicts": [] } ], "pending_deals": [ { "deal": { "id": "5aaa9b059007ba08c9ebaf58", "contact_id": "5aaa9b059007ba08c9ebaf58", "owner_id": "5aba31e99007ba0f570c12f7", "pipeline_id": "5cfa87a4849d7873db082f98", "sales_pipeline_id": "5cfa87a4849d7873db082f98", "name": "Solar panels", "text": "Fingers crossed!", "stage": 50, "status": "pending", "expected_close_date": "2018-04-15", "close_date": "2018-04-15", "date": "2018-04-15", "amount": 99.99, "months": 1, "cost": 0, "margin": 99.99, "total_amount": 99.99, "total_cost": 0, "commission_base": "amount", "commission_type": "none", "commission": 0, "commission_percentage": 0, "reason_lost_id": "5aaa9b059007ba08c9ebaf58", "deal_fields": [], "has_deal_items": true, "deal_items": [], "author": "Jane D.", "has_related_notes": true, "attachments": [], "contact_info": {}, "owner": {}, "previous_pipeline_stages": { "5da7b67a849d78737812437c": 40 }, "created_at": "2018-03-15T16:10:45Z", "modified_at": "2018-03-15T16:10:45Z", "linked_contacts": [ { "id": "68b5edd78b3ee61b685c8692", "contact_name": "Sajed Almorsy", "company": "OnePageCRM", "photo_url": "" } ] } } ], "created_at": "2018-05-16T11:52:09Z", "modified_at": "2018-05-16T11:52:09Z" } }, "lead_sources": [ { "id": "advertisement", "text": "Advertisement", "counts": 4, "total_count": 7, "action_stream_count": 2, "team_counts": [ { "user_id": "5aba31e99007ba0f570c12f7", "counts": 4 } ] } ], "statuses": [ { "status": { "id": "5aead4809007ba56ffca942e", "status": "prospect", "text": "Prospect", "description": "Actively selling to these people", "color": "f96600", "counts": 3, "total_count": 3, "action_stream_count": 2, "team_counts": [ { "user_id": "5aba31e99007ba0f570c12f7", "counts": 4 } ] } } ], "tags": { "tags": [ { "name": "VIP", "counts": 2, "total_count": 4, "action_stream_count": 1 } ], "system_tags": [ { "name": "VIP", "counts": 2, "total_count": 4, "action_stream_count": 1 } ] }, "contacts_count": { "all": [ { "1": 1, "a": 2, "b": 2, "c": 1, "d": 1, "e": 0, "f": 0, "g": 3, "h": 0, "i": 3, "j": 0, "k": 0, "l": 2, "m": 2, "n": 3, "o": 0, "p": 2, "q": 0, "r": 0, "s": 0, "t": 1, "u": 1, "v": 1, "w": 0, "x": 1, "y": 1, "z": 0, "total_count": 27 } ], "users": [ { "1": 1, "a": 2, "b": 2, "c": 1, "d": 1, "e": 0, "f": 0, "g": 3, "h": 0, "i": 3, "j": 0, "k": 0, "l": 2, "m": 2, "n": 3, "o": 0, "p": 2, "q": 0, "r": 0, "s": 0, "t": 1, "u": 1, "v": 1, "w": 0, "x": 1, "y": 1, "z": 0, "total_count": 27, "user_id": "5aba31e99007ba0f570c12f7" } ] }, "team_stream": { "all": 10, "users": [ { "user_id": "5aba31e99007ba0f570c12f7", "counts": 5 } ] } } ``` Standard error responses: 400, 401, 403, 404, 409, 500 — shared across the API. See https://developer.onepagecrm.com/api/errors/. ## Related guides - [Authentication](https://developer.onepagecrm.com/api/authentication/) - [Errors](https://developer.onepagecrm.com/api/errors/) - [Rate limits](https://developer.onepagecrm.com/api/rate-limits/)