Create Contact

Create a new contact

post

/contacts

Creates a new contact in the HealthSherpa system. The contact will be associated with the authenticated agent. All contacts must have an external ID, first name, and last name. This endpoint also supports creating nested resources including drugs, pharmacies, and providers.

Required scopes

This endpoint requires the following scopes:

• : Access to Partner API v2 endpoints

Authorizations

OAuth2authorizationCodeRequired

OAuth 2.0 authentication with partner_api_v2 scope

Authorization URL: Token URL:

Body

Responses

201

Contact created successfully. May return partial_success status if any of the sub-records (drugs, pharmacies, providers) failed to save.

application/json

400

Validation error

application/json

401

Unauthorized - Invalid, missing, or expired OAuth access token. 401 responses for token problems are produced by the OAuth layer and follow the OAuth 2.0 Bearer Token error format ({"error": "...", "error_description": "..."}) rather than the standard {error: {code, message}} envelope used by the rest of the API.

application/json

403

The access token does not have the required partner_api_v2 scope. Like other OAuth errors, this response uses the OAuth 2.0 Bearer Token error format.

application/json

404

Agent not found for the authenticated user

application/json

422

The request was well-formed but could not be processed

application/json

post/contacts

POST /v2/contacts HTTP/1.1
Host: api.medicare.healthsherpa.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 2010

{
  "contact": {
    "external_id": "CRM123456",
    "first_name": "Alex",
    "last_name": "Lee",
    "address_1": "1215 19th St",
    "address_2": "Suite 100",
    "birth_date": "01/15/1955",
    "city": "Sacramento",
    "email": "[e-mail]",
    "extra_help": false,
    "medicaid_eligible": false,
    "medicaid_number": "MED123456",
    "medicare_number": "1EG4TE5MK73",
    "medicare_part_a_effective_date": "01/01/2024",
    "medicare_part_b_effective_date": "01/01/2024",
    "notes": [
      "Initial contact made on 03/20/2024",
      "Interested in Medicare Advantage plans"
    ],
    "phone": "8557722663",
    "sex": "male",
    "state": "CA",
    "type": "client",
    "zip": "95811",
    "authorized_representative_name": "Jane Doe",
    "authorized_representative_relationship": "spouse",
    "authorized_representative_phone_number": "8551234567",
    "authorized_representative_email": "[e-mail]",
    "authorized_representative_address": "456 Oak Ave",
    "authorized_representative_city": "Sacramento",
    "authorized_representative_state": "CA",
    "authorized_representative_zip_code": "95811",
    "mailing_address_street": "789 Mailing Ln",
    "mailing_address_unit_number": "Apt 2B",
    "mailing_address_city": "Sacramento",
    "mailing_address_state": "CA",
    "mailing_address_zip_code": "95811",
    "contact_drugs_attributes": [
      {
        "name": "amoxicillin",
        "drug_type_id": 1,
        "dosage_name": "amoxicillin CAP 250MG",
        "ndc": "54570126563",
        "frequency": 30,
        "user_quantity": 100,
        "id": "drug-1",
        "id_source": "connecture",
        "dosage_id": "dosage-1",
        "dosage_id_source": "connecture"
      }
    ],
    "contact_pharmacies_attributes": [
      {
        "id": "pharm-1",
        "id_source": "connecture",
        "mode": "retail",
        "name": "Neighborhood Pharmacy",
        "npi": "3878698333",
        "primary": true,
        "address_street": "123 Medical Blvd",
        "address_city": "Durham",
        "address_state": "NC",
        "address_zip_code": "27707"
      }
    ],
    "contact_providers_attributes": [
      {
        "id": "provider-1",
        "id_source": "connecture",
        "provider_type": "individual",
        "presentation_name": "Dr. Chelsey Schneider, MD",
        "first_name": "Chelsey",
        "last_name": "Schneider",
        "npi": "1234567890",
        "contact_provider_addresses_attributes": [
          {
            "id": "addr-123",
            "id_source": "connecture",
            "city": "Durham",
            "state": "NC",
            "zip_code": "27707"
          }
        ]
      }
    ]
  }
}

{
  "data": {
    "status": "success",
    "errors": [],
    "contact": {
      "id": "c7716192-7625-4351-a689-3df3b65ba0e2",
      "slug": "jane-testbasic",
      "external_id": "TEST-1738780800000-abc123",
      "first_name": "Jane",
      "last_name": "TestBasic",
      "email": null,
      "birth_date": null,
      "phone": null,
      "address_1": null,
      "address_2": null,
      "city": null,
      "state": null,
      "zip": null,
      "sex": null,
      "type": "lead",
      "medicare_number": null,
      "medicare_part_a_effective_date": null,
      "medicare_part_b_effective_date": null,
      "medicaid_eligible": null,
      "medicaid_number": null,
      "extra_help": null
    },
    "redirect_url": "https://medicare.healthsherpa.com/agents/agent-name/plans/c7716192-7625-4351-a689-3df3b65ba0e2"
  }
}