> ## 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.

# Send an event

> Sends an occurrence of a previously defined custom event. For contact events, identify the contact using one of a contact ID, phone number, or Meta username.



## OpenAPI

````yaml /openapi/endpoints/ycloud-api-v2.yaml post /event/events
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: Emails
  - name: SMS
  - name: Unsubscribers
  - name: Verify
  - name: Voices
  - name: Webhook Endpoints
  - name: WhatsApp Business Accounts
  - name: WhatsApp Inbound Messages
  - name: WhatsApp Media
  - 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
  - name: WhatsApp Group Messages
externalDocs:
  description: Homepage
  url: https://ycloud.com
paths:
  /event/events:
    post:
      tags:
        - Custom Events
      summary: Send an event
      description: >-
        Sends an occurrence of a previously defined custom event. For contact
        events, identify the contact using one of a contact ID, phone number, or
        Meta username.
      operationId: custom_events-send-event
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomEventSendRequest'
            examples:
              byContactId:
                summary: By contact ID
                value:
                  eventName: unique_event_name
                  objectId: '123456789'
              byPhoneNumber:
                summary: By phone number
                value:
                  eventName: unique_event_name
                  contactPhoneNumber: '+16315551111'
              byUsername:
                summary: By Meta username
                value:
                  eventName: unique_event_name
                  contactUsername: customer_demo
        required: true
      responses:
        '200':
          description: Successfully accepted the event. Returns an empty JSON object.
components:
  schemas:
    CustomEventSendRequest:
      type: object
      description: >-
        Contains the properties of the custom event data to be sent.

        For events defined with `objectType` as `CONTACT`, provide one of
        `objectId`, `contactPhoneNumber`, or `contactUsername` to identify the
        contact.

        Only one identifier is used per event. If multiple identifiers are
        provided, a numeric `objectId` takes precedence, followed by a non-blank
        `contactPhoneNumber`, then `contactUsername`.
      required:
        - eventName
      oneOf:
        - required:
            - objectId
        - required:
            - contactPhoneNumber
          not:
            required:
              - objectId
        - required:
            - contactUsername
          not:
            anyOf:
              - required:
                  - objectId
              - required:
                  - contactPhoneNumber
      properties:
        eventName:
          type: string
          description: |-
            Name of the event.
            One of the custom event names you previously defined.
          example: unique_event_name
        occurTime:
          type: string
          format: date-time
          description: >-
            The time at which the event occurred, formatted in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g.,
            `2022-06-01T12:00:00.000Z`,

            if not provided, the current time will be used.
          example: '2022-06-01T12:00:00.000Z'
        objectId:
          type: string
          description: >-
            ID of the object that the event is associated with.

            For events defined with `objectType` as `CONTACT`, provide the
            numeric ID of an existing contact in your account.

            A numeric `objectId` takes precedence over `contactPhoneNumber` and
            `contactUsername`. If that contact is not found, the request fails
            without trying another identifier.
        contactPhoneNumber:
          type: string
          description: >-
            The contact's phone number in E.164 format for events defined with
            `objectType` as `CONTACT`.

            Used when no numeric `objectId` is provided. Looks up a contact in
            your account by phone number and creates one if no match exists.

            Takes precedence over `contactUsername`.
          example: '+16315551111'
        contactUsername:
          type: string
          description: >-
            The Meta username of an existing contact in your account for events
            defined with `objectType` as `CONTACT`. Provide the username saved
            on the contact, without the leading `@`.

            Used when neither a numeric `objectId` nor a non-blank
            `contactPhoneNumber` is provided.

            If no matching contact exists, the request fails. A username does
            not automatically create a contact.
          example: customer_demo
        properties:
          type: object
          description: The properties of the custom event.
          additionalProperties:
            type: object
          example:
            property1: value1
            property2: value2
  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.