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

# Create or reuse a recipient

> Normalizes the phone number and returns the existing recipient when the
authenticated business already has the same normalized phone number.
A new resource returns `201`; a reused resource returns `200`.




## OpenAPI

````yaml /openapi.yaml post /recipients
openapi: 3.1.0
info:
  title: HaulStow Developer Delivery API
  version: 1.0.0
  summary: Create, quote, track, and test HaulStow deliveries.
  description: >
    The HaulStow Developer Delivery API is a server-to-server API for existing

    HaulStow business customers. Authenticate every request with a
    business-bound

    `hsg_live_key_...` API key. Use a test key with the sandbox base URL for

    deterministic, side-effect-free integration testing.


    All JSON responses use the same envelope. Every response includes

    `X-Request-ID` and rate-limit headers. Keep the request ID when contacting

    HaulStow support.
  contact:
    name: HaulStow Developer Support
    email: support@haulstow.co
servers:
  - url: https://developer.haulstow.co/v1
    description: Live
security:
  - DeveloperApiKey: []
tags:
  - name: Quotes
    description: Calculate a delivery quote without creating a delivery.
  - name: Recipients
    description: Manage business-scoped recipients and reusable addresses.
  - name: Deliveries
    description: Create and inspect deliveries created by the authenticated application.
  - name: Sandbox
    description: Test-only helpers that never affect live operations.
  - name: Webhooks
    description: Signed delivery lifecycle callbacks sent by HaulStow.
paths:
  /recipients:
    post:
      tags:
        - Recipients
      summary: Create or reuse a recipient
      description: |
        Normalizes the phone number and returns the existing recipient when the
        authenticated business already has the same normalized phone number.
        A new resource returns `201`; a reused resource returns `200`.
      operationId: createRecipient
      parameters:
        - $ref: '#/components/parameters/XRequestID'
        - $ref: '#/components/parameters/RequiredIdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRecipientRequest'
            example:
              phone_number: '+233245412312'
              name: Ama Mensah
      responses:
        '200':
          description: Existing recipient returned.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestID'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecipientSuccessResponse'
        '201':
          description: Recipient created.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestID'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecipientSuccessResponse'
              example:
                success: true
                statusCode: 201
                message: Recipient created
                data:
                  id: rcp_3f1a821cdb58498cbb52f4706545a089
                  phone_number: '+233245412312'
                  name: Ama Mensah
                  created_at: '2026-08-20T14:20:00Z'
                  updated_at: '2026-08-20T14:20:00Z'
        '400':
          $ref: '#/components/responses/IdempotencyKeyRequired'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/IdempotencyConflict'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    XRequestID:
      name: X-Request-ID
      in: header
      required: false
      description: >
        Optional caller correlation ID. Use 1–128 ASCII letters, digits, `.`,
        `_`,

        `-`, or `:`. Invalid values are replaced. The accepted/generated value
        is

        returned in the response.
      schema:
        type: string
        minLength: 1
        maxLength: 128
        pattern: ^[A-Za-z0-9._:-]+$
      example: req_shop_1842_create
    RequiredIdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: A unique key for this logical mutation. Retained for 24 hours.
      schema:
        type: string
        minLength: 8
        maxLength: 255
      example: shop-order-1842-create-v1
  schemas:
    CreateRecipientRequest:
      type: object
      additionalProperties: false
      required:
        - phone_number
      properties:
        phone_number:
          type: string
          description: Recipient phone number in E.164 form.
          pattern: ^\+[1-9][0-9]{7,14}$
          example: '+233245412312'
        name:
          type: string
          minLength: 1
          maxLength: 255
          example: Ama Mensah
    RecipientSuccessResponse:
      $ref: '#/components/schemas/SuccessEnvelopeRecipient'
    SuccessEnvelopeRecipient:
      type: object
      additionalProperties: false
      required:
        - success
        - statusCode
        - message
        - data
      properties:
        success:
          type: boolean
          const: true
        statusCode:
          type: integer
          enum:
            - 200
            - 201
        message:
          type: string
        data:
          $ref: '#/components/schemas/Recipient'
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
        - success
        - statusCode
        - message
        - error
      properties:
        success:
          type: boolean
          const: false
        statusCode:
          type: integer
          minimum: 400
          maximum: 599
        message:
          type: string
        error:
          $ref: '#/components/schemas/ErrorPayload'
    Recipient:
      type: object
      additionalProperties: false
      required:
        - id
        - phone_number
        - created_at
        - updated_at
      properties:
        id:
          $ref: '#/components/schemas/RecipientID'
        phone_number:
          type: string
          pattern: ^\+[1-9][0-9]{7,14}$
        name:
          type:
            - string
            - 'null'
          maxLength: 255
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    ErrorPayload:
      type: object
      additionalProperties: false
      required:
        - code
      properties:
        code:
          type: string
          description: Stable machine-readable error code.
          example: VALIDATION_ERROR
        details:
          type: object
          additionalProperties: true
          description: >-
            Optional structured context. Do not parse `message` for control
            flow.
    RecipientID:
      type: string
      pattern: ^rcp_[a-f0-9]{32}$
      example: rcp_3f1a821cdb58498cbb52f4706545a089
  headers:
    XRequestID:
      description: Correlation ID for the request.
      schema:
        type: string
      example: 01J5T33T75A8S2JCB37Y6Z5Y4N
    RateLimitLimit:
      description: Maximum requests available in the current window.
      schema:
        type: integer
        minimum: 0
      example: 120
    RateLimitRemaining:
      description: Requests remaining in the current window.
      schema:
        type: integer
        minimum: 0
      example: 119
    RateLimitReset:
      description: Unix timestamp in seconds when the current window resets.
      schema:
        type: integer
        format: int64
      example: 1787236260
    IdempotentReplayed:
      description: >-
        Present and `true` when the response was replayed from an earlier
        completed request.
      schema:
        type: boolean
      example: true
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
        minimum: 1
      example: 30
  responses:
    IdempotencyKeyRequired:
      description: A required `Idempotency-Key` header was not supplied.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/XRequestID'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            statusCode: 400
            message: Idempotency-Key is required
            error:
              code: IDEMPOTENCY_KEY_REQUIRED
    Unauthorized:
      description: >-
        API key is missing, malformed, revoked, expired, or belongs to another
        environment.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/XRequestID'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            invalid:
              value:
                success: false
                statusCode: 401
                message: API key is invalid
                error:
                  code: INVALID_API_KEY
            revoked:
              value:
                success: false
                statusCode: 401
                message: API key has been revoked
                error:
                  code: API_KEY_REVOKED
            expired:
              value:
                success: false
                statusCode: 401
                message: API key has expired
                error:
                  code: API_KEY_EXPIRED
            environment:
              value:
                success: false
                statusCode: 401
                message: API key does not match this environment
                error:
                  code: ENVIRONMENT_MISMATCH
    Forbidden:
      description: The authenticated key lacks the operation's required scope.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/XRequestID'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            statusCode: 403
            message: API key lacks the required scope
            error:
              code: INSUFFICIENT_SCOPE
              details:
                required_scope: deliveries:write
    IdempotencyConflict:
      description: >-
        Idempotency key is missing, in progress, or was reused with a different
        request.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/XRequestID'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            conflict:
              value:
                success: false
                statusCode: 409
                message: Idempotency key was already used with another request
                error:
                  code: IDEMPOTENCY_CONFLICT
            inProgress:
              value:
                success: false
                statusCode: 409
                message: A request with this idempotency key is still in progress
                error:
                  code: IDEMPOTENCY_IN_PROGRESS
    ValidationError:
      description: Request parameters or body are invalid.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/XRequestID'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            validation:
              value:
                success: false
                statusCode: 422
                message: Delivery request is invalid
                error:
                  code: VALIDATION_ERROR
                  details:
                    fields:
                      - field: pickup.latitude
                        message: Latitude must be between -90 and 90
            codGoodsValue:
              value:
                success: false
                statusCode: 422
                message: Goods value is required for COD deliveries
                error:
                  code: COD_GOODS_VALUE_REQUIRED
    RateLimited:
      description: Rate limit exceeded.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/XRequestID'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            statusCode: 429
            message: Too many requests; please try again later
            error:
              code: RATE_LIMIT_EXCEEDED
    InternalError:
      description: Unexpected server error. Quote `X-Request-ID` when contacting support.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/XRequestID'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            statusCode: 500
            message: Internal server error
            error:
              code: INTERNAL_SERVER_ERROR
  securitySchemes:
    DeveloperApiKey:
      type: http
      scheme: bearer
      bearerFormat: hsg_live_key_... or hsg_test_key_...
      description: >
        A business-bound HaulStow API key. Send

        `Authorization: Bearer hsg_live_key_...` to the live server or a

        `hsg_test_key_...` key to the sandbox server. Never expose this key in a
        browser.

````