> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
last_verified: 2026-05-13
title: "Create a contact"
description: "Add a new contact to your contact list in Protocol. You must provide their Protocol username and phone number."
endpoint: "/v1/contacts"
method: "POST"
---


**Endpoint**: `POST /v1/contacts`
**Auth**: `Authorization: Bearer <api_key>` (required)
**Content-Type**: `application/json`
**Error envelope**: 4xx/5xx return `{"error": {"code": string, "message": string}}`


<ApiEndpoint
  method="POST"
  endpoint="/v1/contacts"
  description="This endpoint allows you to add a new contact to your contact list in Protocol. To add a contact, you must provide their Protocol username and phone number."
>
    <section>
      ## Required attributes

      <ApiAttribute
        name="username"
        type="string"
        description="The username for the contact."
        required={true}
      />

      <ApiAttribute
        name="phone_number"
        type="string"
        description="The phone number for the contact."
        required={true}
      />

      ## Optional attributes

      <ApiAttribute
        name="avatar_url"
        type="string"
        description="The avatar image URL for the contact."
        required={false}
      />

      <ApiAttribute
        name="display_name"
        type="string"
        description="The contact display name in the contact list. By default, this is just the username."
        required={false}
      />
    </section>

    <section>
      ## Request example

<MultiLanguageCodeBlock
  languages={["javascript", "bash"]}
  value={[
    { language: "javascript", code: "const val = 1" },
    { language: "bash", code: "wew sdsh" },
  ]}
/>

## Response

<MultiLanguageCodeBlock
  languages={["json"]}
  value={[
    {
      language: "json",
      code: `{
  "text": "Imagine the wildest idea that you've ever had, and you're curious about how it might scale to something that's a 100, a 1,000 times bigger. This is a place where you can get to do that."
}`,
    },
  ]}
/>
</section>

</ApiEndpoint>