> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.bulkneo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send a contact card

> POST /v1/messages/contact — one or more contact cards the recipient can save or call.

Hand someone your support desk's number, or your delivery agent's, as a card they can tap to call or save.

## Notes

* `contacts` takes **1 to 10** cards in one message.
* `full_name` and `phone_number` are required on every card.
* `phone_number` must include the country code — at least **10 digits** after spaces, dashes and brackets are stripped. A shorter number is rejected with `400 invalid_request`.
* `organization`, `email` and `url` are optional extras shown on the card.
* **`email` must look like an address** — something, an `@`, and a domain containing a dot, with no spaces. `not-an-email` is refused with `400 invalid_request` rather than shipped as a card the recipient cannot use.
* **`url` must be a full `http(s)` link.** A bare domain like `example.com` is refused, as is any URL carrying a username or password. Send `https://example.com`, not `example.com`.

## Example

```bash cURL theme={null}
curl -X POST https://api.bulkneo.com/v1/messages/contact \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "YOUR_INSTANCE_ID",
    "to": "919876543210",
    "contacts": [
      {
        "full_name": "Asha Patel",
        "phone_number": "919812345678",
        "organization": "Support desk",
        "email": "asha@example.com"
      },
      {
        "full_name": "Delivery hotline",
        "phone_number": "919811112222"
      }
    ]
  }'
```


## OpenAPI

````yaml api-reference/openapi.json POST /v1/messages/contact
openapi: 3.1.0
info:
  title: BulkNeo WhatsApp API
  version: 1.0.0
  description: >-
    Send WhatsApp messages from your own connected numbers. Every request is
    authenticated with an `apikey` header and names the `instance_id` of the
    number it should be sent from.
servers:
  - url: https://api.bulkneo.com
    description: BulkNeo API
security:
  - apikey: []
tags:
  - name: Messages
    description: Send a message from one of your connected numbers.
  - name: Numbers
    description: Check which numbers are reachable on WhatsApp.
  - name: Instances
    description: Create, connect, inspect and remove your WhatsApp numbers.
  - name: Service
    description: Unauthenticated service health checks.
paths:
  /v1/messages/contact:
    post:
      tags:
        - Messages
      summary: Send a contact card
      description: Sends one or more contact cards the recipient can save or call.
      operationId: sendContact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - instance_id
                - to
                - contacts
              properties:
                instance_id:
                  $ref: '#/components/schemas/InstanceId'
                to:
                  $ref: '#/components/schemas/Recipient'
                contacts:
                  type: array
                  minItems: 1
                  maxItems: 10
                  description: 1 to 10 contact cards.
                  items:
                    type: object
                    required:
                      - full_name
                      - phone_number
                    properties:
                      full_name:
                        type: string
                        maxLength: 100
                        description: The name on the card. Up to 100 characters.
                        example: Asha Patel
                      phone_number:
                        type: string
                        description: >-
                          With country code — at least 10 digits after
                          formatting is stripped.
                        example: '919812345678'
                      organization:
                        type: string
                        maxLength: 100
                        description: Optional company name.
                        example: Support desk
                      email:
                        type: string
                        maxLength: 254
                        format: email
                        description: >-
                          Optional email address. It must look like one —
                          something, an `@`, and a domain containing a dot, with
                          no spaces. A value that is not an address is refused
                          with `400 invalid_request` rather than shipped as an
                          unusable contact card.
                        example: asha@example.com
                      url:
                        type: string
                        maxLength: 512
                        description: >-
                          Optional website. Must be a full `http(s)` URL — a
                          bare domain such as `example.com` is refused, as is
                          any URL containing a username or password.
                        example: https://example.com
                quoted_message_id:
                  $ref: '#/components/schemas/QuotedMessageId'
                quoted_from_me:
                  $ref: '#/components/schemas/QuotedFromMe'
            example:
              instance_id: 3f9c1a2b-7d4e-4c81-9f0a-2b6d5e8c1a34
              to: '919876543210'
              contacts:
                - full_name: Asha Patel
                  phone_number: '919812345678'
                  organization: Support desk
      responses:
        '200':
          $ref: '#/components/responses/SendSuccess'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/InstanceNotFound'
        '409':
          $ref: '#/components/responses/NotConnected'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
components:
  schemas:
    InstanceId:
      type: string
      format: uuid
      description: >-
        Which of your connected numbers to send FROM. Copy it from your numbers
        screen in the portal, or from `GET /v1/instances`. It must belong to
        your account.
      example: 3f9c1a2b-7d4e-4c81-9f0a-2b6d5e8c1a34
    Recipient:
      type: string
      description: >-
        The recipient, with country code and no leading zero — for example
        `919876543210`. Spaces, dashes, brackets and a leading `+` are accepted
        and stripped; 6 to 15 digits must remain.
      example: '919876543210'
    QuotedMessageId:
      type: string
      maxLength: 128
      description: >-
        Send this message as a reply, quoting an earlier one. Use the
        `data.message_id` returned by a previous send.
      example: 3EB0C1D2F4A5B6C7D8E9
    QuotedFromMe:
      type: boolean
      default: false
      description: >-
        Set `true` when the quoted message is one you sent from this number.
        Only valid together with `quoted_message_id`.
    SendData:
      type: object
      properties:
        instance_id:
          type: string
          format: uuid
        to:
          type: string
        type:
          type: string
          description: The message type you sent.
        status:
          type: string
          description: Always `sent` — the message was accepted for delivery.
        message_id:
          type:
            - string
            - 'null'
          description: >-
            The message's own id. Keep it: it is what you quote or react to
            later.
        provider_status:
          type:
            - string
            - 'null'
          description: >-
            The delivery state at the moment of sending, for example `PENDING`.
            It is a snapshot, not a delivery receipt.
    Error:
      type: object
      properties:
        success:
          type: boolean
          const: false
        error:
          type: object
          properties:
            code:
              type: string
              description: >-
                Stable machine-readable code. Branch on this, not on the
                message.
            message:
              type: string
              description: Human-readable explanation. The wording may change.
            details:
              type: object
              description: Extra safe context, present on some errors.
        request_id:
          type: string
          format: uuid
          description: Quote this when asking support about a request.
  responses:
    SendSuccess:
      description: Accepted for delivery.
      headers:
        X-RateLimit-Scope:
          $ref: '#/components/headers/RateLimitScope'
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                const: true
              data:
                $ref: '#/components/schemas/SendData'
              request_id:
                type: string
                format: uuid
          example:
            success: true
            data:
              instance_id: 3f9c1a2b-7d4e-4c81-9f0a-2b6d5e8c1a34
              to: '919876543210'
              type: text
              status: sent
              message_id: 3EB0C1D2F4A5B6C7D8E9
              provider_status: PENDING
            request_id: b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
    BadRequest:
      description: >-
        `invalid_request` a field is missing or malformed (the message names it,
        including its position in a list) · `invalid_media_url` the `url` is not
        a public http(s) link to a file.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: invalid_request
              message: Field "text" is required and must be a non-empty string.
            request_id: b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
    Unauthorized:
      description: >-
        `missing_api_key` no `apikey` header was sent · `invalid_api_key` the
        key is unknown or revoked.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: invalid_api_key
              message: Invalid or revoked API key.
            request_id: b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
    PaymentRequired:
      description: >-
        `no_active_subscription` no usable plan on this account ·
        `subscription_expired` the plan has run out.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: subscription_expired
              message: >-
                Your subscription has expired. Renew it to continue sending
                messages.
            request_id: b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
    Forbidden:
      description: >-
        `account_suspended` · `access_expired` · `trial_quota_exceeded` ·
        `instance_limit_reached` · `activation_unavailable`.


        On `instance_limit_reached`, `details.limit_source` tells you which cap
        you hit: `plan` (the plan you are on — upgrade it) or `account` (a cap
        set on your account — ask your provider to raise it). Branch on that,
        never on the wording of the message.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: trial_quota_exceeded
              message: >-
                Trial message quota reached (500 messages). Upgrade to a paid
                plan to keep sending.
              details:
                trial_message_limit: 500
            request_id: b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
    InstanceNotFound:
      description: >-
        `instance_not_found` — no such instance on your account. The same answer
        is given for an id that does not exist and one that belongs to someone
        else.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: instance_not_found
              message: >-
                Instance not found. Check the instance_id and that it belongs to
                your account.
            request_id: b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
    NotConnected:
      description: >-
        `instance_not_connected` — the number is not connected. Do not retry:
        pause and have someone re-scan the QR.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: instance_not_connected
              message: >-
                This WhatsApp instance is not connected. Connect it before
                sending messages.
            request_id: b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
    Unprocessable:
      description: '`invalid_recipient` — the recipient is not a valid WhatsApp number.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: invalid_recipient
              message: The recipient number is not a valid WhatsApp number.
            request_id: b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
    RateLimited:
      description: >-
        `rate_limit_exceeded` — too many requests this minute. Wait for the
        number of seconds in the `Retry-After` header. `details.scope` and the
        `X-RateLimit-Scope` header say WHICH allowance you exceeded.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
        X-RateLimit-Scope:
          $ref: '#/components/headers/RateLimitScope'
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: rate_limit_exceeded
              message: Rate limit exceeded, retry in 12s.
              details:
                retry_after_seconds: 12
                limit_per_minute: 20
                scope: messages
            request_id: b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
    InternalError:
      description: >-
        `internal_error` — something went wrong on our side. Quote the
        `request_id` to support.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: internal_error
              message: An unexpected error occurred.
            request_id: b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
    UpstreamUnavailable:
      description: >-
        `upstream_unavailable` — the messaging service is temporarily
        unavailable. Safe to retry after a short pause.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: upstream_unavailable
              message: >-
                The messaging service is temporarily unavailable. Please retry
                shortly.
            request_id: b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
  headers:
    RateLimitScope:
      description: >-
        WHICH allowance the other X-RateLimit-* headers describe. `messages`
        covers every /v1/messages/* endpoint and /v1/numbers/check together;
        `instances` is the separate, much larger budget for /v1/instances/*. If
        you cache a limit, cache it against its scope.
      schema:
        type: string
        enum:
          - messages
          - instances
      example: messages
    RateLimitLimit:
      description: Requests allowed per minute on this scope.
      schema:
        type: integer
      example: 20
    RateLimitRemaining:
      description: Requests left in the current minute on this scope.
      schema:
        type: integer
      example: 17
    RateLimitReset:
      description: >-
        Seconds until the allowance next goes up by one. Present on successful
        responses too, so you can pace yourself without first earning a 429. The
        window is a rolling minute, so this is when the oldest request ages out
        — not a fixed reset instant. If `X-RateLimit-Remaining` is above 0 you
        can send now.
      schema:
        type: integer
      example: 43
  securitySchemes:
    apikey:
      type: apiKey
      in: header
      name: apikey
      description: >-
        Your API key, sent in an `apikey` request header. Never in the URL,
        never as a Bearer token.

````