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

# Submit conversion events

> Submits 1 to 100 Lead or Purchase conversion events for the same WhatsApp Business Account.



## OpenAPI

````yaml /openapi/endpoints/ycloud-api-v2.yaml post /ctwa/conversionEvents/batch
openapi: 3.0.0
info:
  description: >-
    The [YCloud](https://ycloud.com) API is organized around
    [REST](https://en.wikipedia.org/wiki/Representational_state_transfer). Our
    API is designed to have predictable, resource-oriented URLs, return
    [JSON](https://www.json.org) responses, and use standard HTTP response codes
    and verbs.
  version: v2
  title: YCloud API
  termsOfService: https://ycloud.com/terms-service
  contact:
    email: service@ycloud.com
servers:
  - url: https://api.ycloud.com/v2
    description: Base URL
security:
  - api_key: []
tags:
  - name: Balance
  - name: Contacts
  - name: Custom Events
  - name: CTWA
  - name: Emails
  - name: SMS
  - name: Unsubscribers
  - name: Verify
  - name: Voices
  - name: Webhook Endpoints
  - name: WhatsApp Business Accounts
  - name: WhatsApp Inbound Messages
  - name: WhatsApp Media
  - name: Messenger Messages
  - name: WhatsApp Messages
  - name: WhatsApp Blocked Users
  - name: WhatsApp Groups
  - name: WhatsApp Calling
  - name: WhatsApp Phone Numbers
  - name: WhatsApp Templates
  - name: WhatsApp Flows
  - name: Meta Business Agent
externalDocs:
  description: Homepage
  url: https://ycloud.com
paths:
  /ctwa/conversionEvents/batch:
    post:
      tags:
        - CTWA
      summary: Submit conversion events
      description: >-
        Submits 1 to 100 Lead or Purchase conversion events for the same
        WhatsApp Business Account.
      operationId: ctwa_conversion_event-submit-batch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CtwaConversionEventBatchRequest'
            examples:
              mixedEvents:
                summary: Lead and Purchase for the same click
                value:
                  wabaId: '102012345678901'
                  events:
                    - ctwaClid: REPLACE_WITH_REAL_CTWA_CLID
                      eventName: Lead
                      eventTime: 1794798000
                    - ctwaClid: REPLACE_WITH_REAL_CTWA_CLID
                      eventName: Purchase
                      eventTime: 1794798000
                      customData:
                        value: 49.99
                        currency: USD
                        orderId: ORDER-20261116-001
                        contentIds:
                          - SKU-001
                        contentName: Example product
      responses:
        '200':
          description: >-
            Processing completed. Inspect each result status; event failures
            also use HTTP 200.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CtwaConversionEventBatchResponse'
              examples:
                partialFailure:
                  summary: Results preserve input order
                  value:
                    results:
                      - wabaId: '102012345678901'
                        ctwaClid: REPLACE_WITH_REAL_CTWA_CLID
                        eventName: Lead
                        eventTime: 1794798000
                        status: succeeded
                        index: 0
                      - wabaId: '102012345678901'
                        ctwaClid: REPLACE_WITH_REAL_CTWA_CLID
                        eventName: Purchase
                        eventTime: 1794798000
                        status: failed
                        error:
                          code: CONVERSION_ALREADY_REPORTED
                          message: >-
                            This click and event type already has an API success
                            within 28 days.
                          retryable: false
                        index: 1
        '400':
          description: >-
            Invalid JSON or top-level request fields (PARAM_INVALID).
            Event-level validation failures are returned in HTTP 200 results
            instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '403':
          description: >-
            The WABA is unavailable to this account
            (WHATSAPP_BUSINESS_ACCOUNT_UNAVAILABLE), or the Custom app lacks
            permission or WABA access. A Custom app request may also be rejected
            during authorization when wabaId cannot be read from the body. The
            whole request is rejected.
components:
  schemas:
    CtwaConversionEventBatchRequest:
      type: object
      required:
        - wabaId
        - events
      properties:
        wabaId:
          type: string
          minLength: 1
          description: >-
            WhatsApp Business Account ID available to the account authenticated
            by the API key. The WABA must be connected to YCloud and have valid
            authorization.
          example: '102012345678901'
        events:
          type: array
          minItems: 1
          maxItems: 100
          description: 1 to 100 events for the same WABA. Results preserve this order.
          items:
            $ref: '#/components/schemas/CtwaConversionEvent'
    CtwaConversionEventBatchResponse:
      type: object
      required:
        - results
      properties:
        results:
          type: array
          minItems: 1
          maxItems: 100
          description: >-
            One result for each input event, in input order. Each result
            includes its zero-based index. A failed item does not stop
            subsequent items.
          items:
            $ref: '#/components/schemas/CtwaConversionResult'
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/Error'
          description: >-
            Contains the error code and human-readable message for the API
            error.
    CtwaConversionEvent:
      type: object
      description: >-
        One conversion event in a batch. Uses the batch request's top-level
        wabaId.
      required:
        - ctwaClid
        - eventName
        - eventTime
      properties:
        ctwaClid:
          type: string
          minLength: 1
          description: >-
            Click-to-WhatsApp click identifier from referral.ctwa_clid in an
            inbound WhatsApp message. Must be nonblank and at most 1024 UTF-8
            bytes. Use the original identifier for the selected WABA; Meta
            determines click validity.
          example: REPLACE_WITH_REAL_CTWA_CLID
        eventName:
          type: string
          enum:
            - Lead
            - Purchase
          description: >-
            Conversion type. Lead is sent to Meta as LeadSubmitted; Purchase is
            sent as Purchase. Values are case-sensitive.
          example: Purchase
        eventTime:
          type: integer
          format: int64
          minimum: 1
          description: >-
            Actual conversion time as a positive Unix timestamp in seconds, not
            milliseconds. Must not be later than the current server time. Meta
            may reject events or clicks outside its accepted time window.
          example: 1794798000
        customData:
          $ref: '#/components/schemas/CtwaConversionCustomData'
    CtwaConversionResult:
      type: object
      required:
        - status
      description: >-
        Result for one event. Failed results omit identity fields that could not
        be validated. index is present only in batch results.
      properties:
        index:
          type: integer
          minimum: 0
          description: >-
            Zero-based position in the batch events array. Returned for every
            batch item; omitted for single submissions.
          example: 0
        wabaId:
          type: string
          description: WABA ID used for this submission.
          example: '102012345678901'
        ctwaClid:
          type: string
          description: Validated click identifier from the request.
          example: REPLACE_WITH_REAL_CTWA_CLID
        eventName:
          type: string
          enum:
            - Lead
            - Purchase
          description: Validated conversion type from the request.
          example: Purchase
        eventTime:
          type: integer
          format: int64
          description: Validated conversion time from the request, in Unix seconds.
          example: 1794798000
        status:
          type: string
          enum:
            - succeeded
            - failed
          description: >-
            succeeded means the Meta request returned normally and YCloud saved
            the success record. It does not guarantee Meta ad attribution or
            dashboard visibility. Inspect this field even when the HTTP status
            is 200.
          example: succeeded
        error:
          $ref: '#/components/schemas/CtwaConversionError'
    Error:
      type: object
      required:
        - status
        - code
      properties:
        status:
          type: integer
          format: int32
          pattern: '[45]\d{2}'
          description: >-
            HTTP status code, [RFC 7231, Section
            6](https://datatracker.ietf.org/doc/html/rfc7231#section-6). It
            conveys the HTTP status code used for the convenience of the
            consumer.
          example: 404
        code:
          type: string
          description: >-
            One of a server-defined error codes. Some `4xx` errors that could be
            handled programmatically include an error code that briefly explains
            the error reported.
          example: NOT_FOUND
        message:
          type: string
          description: >-
            A human-readable representation of the error. It is intended as an
            aid to developers and is not suitable for exposure to end users.
          example: The requested resource does not exist.
        target:
          type: string
          description: The target of the error.
          example: ''
        docUrl:
          type: string
          description: A URL to more information about the error.
          example: ''
        requestId:
          type: string
          description: >-
            Each API request has an associated request ID. It conveys the
            response header `YCloud-Request-ID` used for the convenience of the
            consumer.
          example: req_1KjtKI80IKoaJNa6n6p
        whatsappApiError:
          $ref: '#/components/schemas/WhatsappApiError'
          description: >-
            The original error object returned by WhatsApp. See [Handling
            Errors](https://developers.facebook.com/docs/graph-api/guides/error-handling),
            [Cloud API Error
            Codes](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes).


            Note: This field is returned if we tried to request the WhatsApp
            Business API and got an error response.
        metaBusinessAgentApiError:
          $ref: '#/components/schemas/MetaBusinessAgentApiError'
          description: >-
            Sanitized upstream details returned when a Meta Business Agent
            request fails.
        messengerApiError:
          $ref: '#/components/schemas/MessengerApiError'
          description: >-
            Numeric Meta diagnostics for a confirmed Messenger submission
            refusal. Omitted when unavailable.
    CtwaConversionCustomData:
      type: object
      description: >-
        Additional conversion data sent to Meta. Required for Purchase,
        including both value and currency. For Lead, this object is optional;
        value and currency must either both be supplied or both be omitted. Omit
        optional fields instead of sending null.
      properties:
        value:
          type: number
          minimum: 0
          description: >-
            Conversion value, required for Purchase. Must be a non-negative JSON
            number with at most 18 significant digits; numeric strings are not
            accepted. Supply currency together with value.
          example: 49.99
        currency:
          type: string
          pattern: ^[a-zA-Z]{3}$
          description: >-
            Valid three-letter ISO 4217 currency code, required for Purchase.
            Uppercase and lowercase are accepted; converted to uppercase when
            sent to Meta. Supply value together with currency.
          example: USD
        orderId:
          type: string
          maxLength: 256
          description: >-
            Merchant order identifier, sent as Meta custom_data.order_id.
            Maximum 256 UTF-16 code units. This field is not a YCloud
            deduplication key.
          example: ORDER-20261116-001
        contentIds:
          type: array
          maxItems: 100
          description: >-
            Product identifiers, sent as Meta custom_data.content_ids. Up to 100
            items. Each item must be nonblank and at most 256 UTF-16 code units.
          items:
            type: string
            minLength: 1
            maxLength: 256
          example:
            - SKU-001
        contentName:
          type: string
          maxLength: 256
          description: >-
            Product or content name, sent as Meta custom_data.content_name.
            Maximum 256 UTF-16 code units.
          example: Example product
    CtwaConversionError:
      type: object
      description: >-
        Returned only when status is failed; omitted on success. Per-event
        failure codes and their retryable values:


        | code | retryable | Meaning |

        | --- | --- | --- |

        | INVALID_CONVERSION_EVENT | false | Invalid event fields; correct the
        request before retrying. |

        | CONVERSION_ALREADY_REPORTED | false | A successful API submission
        exists for the same account, ctwaClid, and eventName within the previous
        28 days. Single and batch submissions share this check; Lead and
        Purchase are checked separately. Concurrent requests are not guaranteed
        to be deduplicated. |

        | CONVERSION_TEMPORARILY_UNAVAILABLE | true | The success-record check
        or submission service is unavailable; the submission outcome may be
        unknown. |

        | WABA_AUTHORIZATION_FAILED | false | WABA authorization is unavailable;
        restore authorization before resubmitting. |

        | DATASET_UNAVAILABLE | true | The WABA conversion dataset could not be
        obtained. |

        | META_REQUEST_FAILED | true | The Meta request failed. Check the
        message and correct invalid data before retrying. |

        | CONVERSION_RECORD_SAVE_FAILED | true | Meta returned normally, but the
        success record could not be saved; retrying may send to Meta again. |
      required:
        - code
        - message
        - retryable
      properties:
        code:
          type: string
          enum:
            - INVALID_CONVERSION_EVENT
            - CONVERSION_ALREADY_REPORTED
            - CONVERSION_TEMPORARILY_UNAVAILABLE
            - WABA_AUTHORIZATION_FAILED
            - DATASET_UNAVAILABLE
            - META_REQUEST_FAILED
            - CONVERSION_RECORD_SAVE_FAILED
          example: CONVERSION_ALREADY_REPORTED
        message:
          type: string
          description: >-
            Failure details. Message text can vary; use code for programmatic
            handling.
          example: This click and event type already has an API success within 28 days.
        retryable:
          type: boolean
          description: >-
            Whether another attempt may be made. true does not guarantee a
            successful or duplicate-free retry: a timeout or save failure may
            occur after Meta has received the event. Correct invalid data or
            authorization before retrying.
          example: false
    WhatsappApiError:
      type: object
      description: >-
        The original error object returned by WhatsApp. See [Handling
        Errors](https://developers.facebook.com/docs/graph-api/guides/error-handling),
        [Cloud API Error
        Codes](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes).
      required:
        - message
        - code
      properties:
        message:
          type: string
          description: A human-readable description of the error.
          example: HSM Template creation failed
        code:
          type: string
          description: An error code.
          example: 200002
        type:
          type: string
          description: Error type.
          example: OAuthException
        is_transient:
          type: boolean
          description: Whether the error is transient.
          example: false
        error_subcode:
          type: string
          description: Additional code about the error.
          example: 2388109
        error_user_msg:
          type: string
          description: >-
            The message to display to the user. The language of the message is
            based on the locale of the API request.
          example: This message template cannot be created.
        error_user_title:
          type: string
          description: >-
            The title of the dialog, if shown. The language of the message is
            based on the locale of the API request.
          example: Message Cannot Be Submitted
        fbtrace_id:
          type: string
          description: >-
            Internal support identifier. When reporting a bug related to a Graph
            API call, include the fbtrace_id to help us find log data for
            debugging.
          example: AVGjJ7ia2zJkrHG
        error_data:
          description: >-
            Additional data about the error. A string or map.

            - For template APIs, this field is a string describing the reason
            for the error.

            - For message APIs, this field is a map with property `details`
            describing the reason for the error.
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
    MetaBusinessAgentApiError:
      type: object
      description: Sanitized details from a failed Meta Business Agent upstream request.
      properties:
        title:
          type: string
        detail:
          type: string
        type:
          type: string
        status:
          type: integer
          format: int32
        requestId:
          type: string
    MessengerApiError:
      type: object
      description: >-
        Numeric provider diagnostics only. Does not contain raw Meta error text
        or access credentials.
      required:
        - code
      properties:
        code:
          type: string
          description: Meta error code, encoded as a string.
          example: '100'
        subcode:
          type: string
          description: >-
            Meta error subcode, encoded as a string. Omitted if Meta did not
            provide it.
          example: '2018276'
  securitySchemes:
    api_key:
      type: apiKey
      name: X-API-Key
      in: header

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.