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

# Claim Recovered Signup Attempt

> Claim a recovered signup attempt to complete the WhatsApp Business Account connection. This is used when the user completed the Embedded Signup flow on Meta's side but didn't return to Chirp to finalize the setup. The attempt must be in 'recovered' status and belong to the authenticated organization.



## OpenAPI

````yaml /openapi.json post /v1/organization/whatsapp/business-profiles/claim
openapi: 3.1.0
info:
  version: 1.0.0
  title: Chirp API
  description: Communication APIs for SMS, MMS, and WhatsApp messaging
servers:
  - url: https://api.buildwithchirp.com
security: []
paths:
  /v1/organization/whatsapp/business-profiles/claim:
    post:
      tags:
        - Admin
        - WhatsApp Business Profiles
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClaimRecoveredAttemptRequest'
      responses:
        '201':
          description: Business profile created successfully from claimed attempt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessProfileResponse'
        '400':
          description: Invalid request - attempt cannot be claimed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Signup attempt not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: >-
            WhatsApp Business Account already connected Possible codes:
            `resource_already_exists`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '424':
          description: >-
            Meta API request failed Possible codes: `meta_api_error`,
            `meta_api_unavailable`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
        - adminAuth: []
components:
  schemas:
    ClaimRecoveredAttemptRequest:
      type: object
      properties:
        attemptId:
          type: string
          pattern: ^wss_[a-zA-Z0-9]+$
          example: wss_2DbBs7GWhGvVNJGrDXr5RG0mBWI
          description: The ID of the recovered signup attempt to claim
      required:
        - attemptId
    BusinessProfileResponse:
      type: object
      properties:
        id:
          type: string
          pattern: ^wabp_[a-zA-Z0-9]+$
          example: wabp_2DbBs7GWhGvVNJGrDXr5RG0mBWI
          description: WhatsApp Business Profile ID
        organizationId:
          type: string
        metaWabaId:
          type: string
          description: Meta's WhatsApp Business Account ID
        metaBusinessId:
          type:
            - string
            - 'null'
          description: Meta's Business Portfolio ID
        businessName:
          type:
            - string
            - 'null'
          example: Acme Corp
          description: Business name from Meta
        tokenExpiresAt:
          type:
            - string
            - 'null'
          format: date-time
          description: When the access token expires (null = never)
        onboardingCompletedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: When onboarding was completed
        reviewDecision:
          type:
            - string
            - 'null'
          enum:
            - APPROVED
            - REJECTED
            - PENDING
            - DEFERRED
          description: >-
            Latest WABA policy review outcome from Meta's account_review_update
            webhook
        reviewDecidedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: When Meta last decided the WABA review
        createdAt:
          type: string
          format: date-time
        phoneNumbers:
          type: array
          items:
            $ref: '#/components/schemas/BusinessProfilePhoneNumber'
        isTestProfile:
          type: boolean
          description: Whether this is a test profile (for test mode separation)
      required:
        - id
        - organizationId
        - metaWabaId
        - metaBusinessId
        - businessName
        - tokenExpiresAt
        - onboardingCompletedAt
        - reviewDecision
        - reviewDecidedAt
        - createdAt
        - phoneNumbers
        - isTestProfile
    ApiError:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - invalid_request_error
                - authentication_error
                - provider_error
                - api_error
              description: The type of error returned
              example: invalid_request_error
            code:
              type: string
              enum:
                - message_undeliverable
                - conversation_window_expired
                - recipient_not_on_whatsapp
                - phone_number_not_assigned
                - unsupported_message_type
                - media_too_large
                - invalid_phone_number
                - template_not_found
                - template_parameter_mismatch
                - groups_not_eligible
                - account_restricted
                - display_name_not_approved
                - whatsapp_not_configured
                - meta_api_error
                - meta_api_unavailable
                - telnyx_api_error
                - telnyx_api_unavailable
                - rate_limit_exceeded
                - whatsapp_rate_limited
                - resource_already_exists
                - test_app_required
                - call_not_found
                - call_already_ended
                - call_failed
                - call_rejected
                - call_timeout
                - call_busy
                - calling_not_configured
                - calling_disabled
                - max_concurrent_calls_reached
                - recording_not_found
                - recording_already_in_progress
                - recording_failed
                - voicemail_not_found
                - voicemail_disabled
                - invalid_call_command
                - command_not_applicable
                - whatsapp_calling_not_enabled
                - whatsapp_call_permission_required
                - whatsapp_call_permission_limit
                - whatsapp_pstn_bridge_forbidden
                - livekit_api_error
                - livekit_room_error
                - sip_trunk_error
              description: A machine-readable error code for programmatic handling
              example: invalid_phone_number
            message:
              type: string
              description: Human-readable error message
              example: The phone number "+1abc" is not in E.164 format.
            doc_url:
              type: string
              format: uri
              description: URL to documentation for this error code
              example: >-
                https://docs.buildwithchirp.com/api_reference/error-codes#invalid_phone_number
            param:
              type: string
              description: The parameter that caused the error
              example: from
            provider:
              $ref: '#/components/schemas/ProviderError'
            additional_info:
              type: array
              items:
                type: string
              description: Human-readable remediation hints (e.g. from Meta Health Status).
          required:
            - type
            - message
      required:
        - error
    BusinessProfilePhoneNumber:
      type: object
      properties:
        id:
          type: string
        displayPhoneNumber:
          type: string
          example: '+15551234567'
          description: Phone number in E.164 format
        metaPhoneNumberId:
          type: string
          description: Meta's internal phone number ID
        verified:
          type: boolean
          description: Whether the phone number is verified
        qualityRating:
          type:
            - string
            - 'null'
          example: GREEN
          description: Quality rating from Meta (GREEN, YELLOW, RED)
      required:
        - id
        - displayPhoneNumber
        - metaPhoneNumberId
        - verified
        - qualityRating
    ProviderError:
      type: object
      properties:
        source:
          type: string
          enum:
            - meta
            - telnyx
            - livekit
          description: Provider name
          example: meta
        code:
          anyOf:
            - type: number
            - type: string
          description: Provider's native error code
        message:
          type: string
          description: Provider's error message
        fbtrace_id:
          type: string
          description: Meta's trace ID for support tickets
        health_status:
          $ref: '#/components/schemas/HealthStatusPayload'
      required:
        - source
        - code
        - message
    HealthStatusPayload:
      type: object
      properties:
        can_send_message:
          type: string
          enum:
            - AVAILABLE
            - LIMITED
            - BLOCKED
          description: Meta Health Status value
        entities:
          type: array
          items:
            $ref: '#/components/schemas/HealthStatusEntity'
      required:
        - can_send_message
        - entities
      description: >-
        Meta Health Status payload, present when the error was enriched via the
        Health Status API.
    HealthStatusEntity:
      oneOf:
        - type: object
          properties:
            entity_type:
              type: string
              enum:
                - PHONE_NUMBER
                - MESSAGE_TEMPLATE
                - WABA
                - BUSINESS
                - APP
            id:
              type: string
            can_send_message:
              type: string
              enum:
                - AVAILABLE
            can_receive_call_sip:
              type: string
              enum:
                - AVAILABLE
                - LIMITED
                - BLOCKED
              description: Meta Health Status value
            errors:
              type: array
              items:
                $ref: '#/components/schemas/HealthStatusError'
          required:
            - entity_type
            - id
            - can_send_message
        - type: object
          properties:
            entity_type:
              type: string
              enum:
                - PHONE_NUMBER
                - MESSAGE_TEMPLATE
                - WABA
                - BUSINESS
                - APP
            id:
              type: string
            can_send_message:
              type: string
              enum:
                - LIMITED
            can_receive_call_sip:
              type: string
              enum:
                - AVAILABLE
                - LIMITED
                - BLOCKED
              description: Meta Health Status value
            additional_info:
              type: array
              items:
                type: string
            errors:
              type: array
              items:
                $ref: '#/components/schemas/HealthStatusError'
          required:
            - entity_type
            - id
            - can_send_message
            - additional_info
        - type: object
          properties:
            entity_type:
              type: string
              enum:
                - PHONE_NUMBER
                - MESSAGE_TEMPLATE
                - WABA
                - BUSINESS
                - APP
            id:
              type: string
            can_send_message:
              type: string
              enum:
                - BLOCKED
            can_receive_call_sip:
              type: string
              enum:
                - AVAILABLE
                - LIMITED
                - BLOCKED
              description: Meta Health Status value
            errors:
              type: array
              items:
                $ref: '#/components/schemas/HealthStatusError'
          required:
            - entity_type
            - id
            - can_send_message
            - errors
    HealthStatusError:
      type: object
      properties:
        error_code:
          type: number
        error_description:
          type: string
        possible_solution:
          type: string
      required:
        - error_code
        - error_description
        - possible_solution
  securitySchemes:
    adminAuth:
      type: http
      scheme: bearer
      description: 'Admin API key (format: sk_admin_*) for organization-level operations'

````