Elocuenti Account API

openapi: 3.2.0
info:
  title: Elocuenti Account API
  version: 1.0.0
  description: 'The public REST API of Elocuenti: contacts, conversations, funnels, WhatsApp templates, knowledge base, automations, events, AI calls, webhooks and charges (Colombia).


    Authenticate every request with `Authorization: Bearer `. A key that starts with `eloc_live_` acts in production; one that starts with `eloc_sand_` is a sandbox key: it never messages or calls your customers, and the **Sandbox** line of each operation says what it does instead. Create keys in Settings → API Keys.


    Guides and reference: https://www.elocuenti.com/api/docs'
servers:
- url: https://www.elocuenti.com
tags:
- name: Account
paths:
  /api/v1/me:
    get:
      tags:
      - Account
      summary: Get the business and the API key in use
      description: 'Returns the business your API key belongs to, the key itself (name, environment, permissions, expiry) and its limits. Call it first: it tells you that the key works and what it can do.


        **Permission:** any valid key · **Sandbox:** reads your real data'
      operationId: get_me
      security:
      - ApiKey: []
      x-access:
        permission: none
        sandbox: readsReal
      responses:
        '200':
          description: The business, the key and its limits.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  responses:
    Forbidden:
      description: 'The API key is valid but cannot do this.


        - `forbidden`: The API key does not have the permission this operation needs. Create a new key with the permission the operation documents: the permissions of a key are set when it is created.

        - `legacy_key_not_allowed`: This operation is not available to the original business key (the one that starts with `eloq_` or `elocuenti_`). Create an API key in Settings → API Keys (it starts with `eloc_live_` or `eloc_sand_`) and use it.

        - `creator_cannot_attend_conversations`: The team that attends conversations is not shown to this key, because the person who created it does not attend conversations. Read the team with a key created by an owner or an administrator.

        - `sandbox_not_supported`: This operation is not available with a sandbox key. Use a production key (`eloc_live_`), or check the operation''s page to see how it behaves in sandbox.

        - `webhook_content_not_allowed`: Receiving the text of the messages needs a key with the `conversations:read` permission that was created by an owner or an administrator. The text of every message of the business would reach your address, so it is limited to who can read all the conversations. Create the subscription (or change it) with a key made by an owner or an administrator that holds `conversations:read`, or leave `include_message_content` off and read each message with the API.

        - `calls_not_available`: The business''s plan or billing status does not allow outbound calls. Nothing was dialed. Check the plan and the billing status in the dashboard (for example, a trial does not include voice calls).'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: 'Too many requests.


        - `whatsapp_rate_limited`: WhatsApp is limiting how fast the business can create or delete templates. Wait a few minutes and try again with the same Idempotency-Key. WhatsApp allows a limited number of new templates per hour.

        - `call_capacity_reached`: All the business''s phone lines for AI calls are busy right now. Nothing was dialed. Wait the seconds in the `Retry-After` header and send the request again; some lines are always kept free for your team''s own calls.

        - `rate_limit_exceeded`: Too many requests: the limit was reached. Wait the seconds in the `Retry-After` header and try again. Your key''s limits are in `GET /api/v1/me`.

        - `daily_limit_exceeded`: This API key reached the number of changes it can make in a day for this operation. Nothing was changed. Send only what changed since your last sync, or wait until tomorrow; the day''s limit is in the operation''s page.'
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: 'Something went wrong on our side.


        - `internal_error`: An unexpected error happened on our side. Do not blindly repeat a write: check whether it was applied, or repeat it with the same Idempotency-Key. If it keeps failing, write to us with the `request_id`.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServiceUnavailable:
      description: 'The service could not complete the request.


        - `temporary_conflict`: The request collided with another change made at the same moment and was not applied. Send it again right away: nothing was changed, so repeating it is safe.

        - `outcome_unknown`: We could not confirm whether the operation was completed. If the operation accepts an Idempotency-Key, repeat it with the same key: if it was already applied, you will get the same result. If it does not accept one, check the state before repeating it.

        - `service_unavailable`: The service cannot answer right now. Try again in a few seconds. If it persists, write to us at contacto@elocuenti.com with the `request_id` of the answer.'
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: 'The API key was not accepted.


        - `missing_api_key`: The request has no API key. Send it in the Authorization header: `Authorization: Bearer <your key>`.

        - `invalid_api_key`: The API key is not recognized. Check that it is complete and was copied correctly. If it still fails, create a new one in Settings → API Keys.

        - `api_key_expired`: The API key has expired. Create a new key in Settings → API Keys and use it instead.

        - `api_key_inactive`: The API key was revoked. Create a new key in Settings → API Keys and use it instead.

        - `api_key_owner_inactive`: The person who created this key is no longer active in the business. Ask an owner or administrator to transfer it to another person in Settings → API Keys, or create a new one.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  headers:
    X-RateLimit-Reset:
      description: 'The moment that window ends, as a Unix timestamp (seconds since 1970-01-01 UTC). It is not the seconds to wait: for that, use `Retry-After`.'
      schema:
        type: integer
    X-RateLimit-Limit:
      description: How many requests the key may make in the window that applies to this answer.
      schema:
        type: integer
    Retry-After:
      description: 'When the answer asks you to wait (a rate limit, a request still being processed, a temporary failure): how many seconds to wait before sending the request again.'
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: How many requests are left in that window.
      schema:
        type: integer
    X-Request-Id:
      description: The identifier of this request, also in the body as `request_id`. Send your own `X-Request-Id` (up to 128 letters, digits, `.`, `_`, `:` or `-`) and it comes back unchanged, so you can match your logs with ours.
      schema:
        type: string
  schemas:
    MeBusiness:
      type: object
      properties:
        id:
          type: string
          description: The identifier of your business.
          examples:
          - 00000000-0000-4000-8000-0000000000a1
          title: Id
        name:
          anyOf:
          - type: string
          - type: 'null'
          examples:
          - Tienda Ejemplo
          description: The name of your business, as shown in the dashboard.
          title: Name
      required:
      - id
      - name
      description: The business the API key belongs to.
      title: MeBusiness
    FieldIssue:
      type: object
      properties:
        field:
          type: string
          description: 'The field that failed: its name, or a dotted path for a nested one (`items.0.name`).'
          examples:
          - name
          title: Field
        issue:
          type: string
          description: 'What is wrong with it: `required`, `invalid_type`, `invalid_format`, `too_small`, `too_big`, `invalid_value` or `unrecognized_field`. An operation that refers to another resource by id can also say `not_found` (that id does not exist in your business) or a reason specific to it, which its page explains. It never repeats the value you sent.'
          examples:
          - required
          title: Issue
      required:
      - field
      - issue
      description: One field that did not pass validation.
      title: FieldIssue
    MeLimits:
      type: object
      properties:
        requests_per_minute:
          type: integer
          description: How many requests the key may make per minute.
          examples:
          - 100
          title: Requests Per Minute
        requests_per_hour:
          type: integer
          description: How many requests the key may make per hour.
          examples:
          - 1000
          title: Requests Per Hour
      required:
      - requests_per_minute
      - requests_per_hour
      description: The limits of the key. Past them the API answers `429` with `Retry-After`; each answer also carries `X-RateLimit-*` headers.
      title: MeLimits
    MeCreator:
      type: object
      properties:
        id:
          type: string
          description: The identifier of the person.
          examples:
          - 00000000-0000-4000-8000-0000000000b2
          title: Id
      required:
      - id
      description: 'The person who created the key. The key acts on their behalf: it can only do what they are allowed to do in the business. Only their identifier is shown, never their name: whoever holds the key may not be them, and their name is in the dashboard.'
      title: MeCreator
    Me:
      type: object
      properties:
        business:
          $ref: '#/components/schemas/MeBusiness'
        key:
          $ref: '#/components/schemas/MeKey'
        limits:
          $ref: '#/components/schemas/MeLimits'
      required:
      - business
      - key
      - limits
      description: The business, the key and its limits.
      title: Me
    Error:
      type: object
      properties:
        error:
          type: string
          description: What happened and what to do about it, in English or Spanish (it follows the `Accept-Language` header). Meant for a person; do not parse it.
          examples:
          - The API key has expired. Create a new key in Settings → API Keys and use it instead.
          title: Error
        code:
          type: string
          enum:
          - missing_api_key
          - invalid_api_key
          - api_key_expired
          - api_key_inactive
          - forbidden
          - legacy_key_not_allowed
          - creator_cannot_attend_conversations
          - api_key_owner_inactive
          - sandbox_not_supported
          - not_found
          - media_expired
          - media_not_ready
          - conflict
          - template_name_taken
          - template_being_created
          - template_content_rejected
          - template_limit_reached
          - whatsapp_not_connected
          - whatsapp_connection_unavailable
          - whatsapp_rate_limited
          - webhook_limit_reached
          - rotation_in_progress
          - webhook_url_taken
          - webhook_content_not_allowed
          - webhook_inactive
          - contact_cannot_be_called
          - call_outside_window
          - calls_not_available
          - phone_line_unavailable
          - call_capacity_reached
          - call_in_progress
          - call_not_placed
          - request_in_progress
          - idempotency_key_reused
          - invalid_json
          - invalid_request
          - payload_too_large
          - rate_limit_exceeded
          - daily_limit_exceeded
          - temporary_conflict
          - outcome_unknown
          - service_unavailable
          - internal_error
          description: A stable identifier of the error. Branch on this, not on `error`. Every code is explained in the error guide.
          examples:
          - api_key_expired
          title: Code
        request_id:
          type: string
          description: The identifier of this request. Give it to support if you need help.
          examples:
          - 3f9a1c07d2b4
          title: Request Id
        details:
          description: 'On `invalid_request`: one entry per field that failed. A `404` or `409` that blames one field of your request (for example, an id that does not exist) names it here too.'
          type: array
          items:
            $ref: '#/components/schemas/FieldIssue'
          title: Details
        doc_url:
          type: string
          description: The section of the error guide that explains this code.
          examples:
          - https://www.elocuenti.com/api/docs/errors#api_key_expired
          title: Doc Url
      required:
      - error
      - code
      - request_id
      - doc_url
      description: The body of an error answer.
      title: Error
    MeKey:
      type: object
      properties:
        id:
          type: string
          description: The identifier of the key (not the secret).
          examples:
          - 00000000-0000-4000-8000-0000000000c3
          title: Id
        name:
          type: string
          description: The name you gave the key when you created it.
          examples:
          - Integración tienda online
          title: Name
        environment:
          type: string
          enum:
          - production
          - sandbox
          description: '`production` acts on your real business. `sandbox` is for testing: it never sends a message to your customers, never calls them and never moves real money, and reads show the real data of your business; what each write does with it is in its access line.'
          examples:
          - sandbox
          title: Environment
        permissions:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: 'What the key may do: for each resource, the actions allowed (`read`, `write`, `delete`). An operation needs the permission its access line names (`x-access.permission`).'
          examples:
          - contacts:
            - write
          title: Permissions
        created_at:
          type: string
          description: When the key was created (UTC, ISO 8601).
          examples:
          - '2026-10-01T15:04:05.000Z'
          title: Created At
        expires_at:
          anyOf:
          - type: string
          - type: 'null'
          examples:
          - null
          description: When the key stops working (UTC, ISO 8601), or `null` if it does not expire.
          title: Expires At
        last_used_at:
          anyOf:
          - type: string
          - type: 'null'
          examples:
          - '2026-10-27T12:00:00.000Z'
          description: The last time the key was used (UTC, ISO 8601), or `null` if it never was. It is approximate.
          title: Last Used At
        created_by:
          $ref: '#/components/schemas/MeCreator'
      required:
      - id
      - name
      - environment
      - permissions
      - created_at
      - expires_at
      - last_used_at
      - created_by
      description: The API key making the request.
      title: MeKey
    MeResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Me'
        request_id:
          type: string
          description: The identifier of this request. Give it to support if you need help.
          examples:
          - 3f9a1c07d2b4
          title: Request Id
      required:
      - data
      - request_id
      title: MeResponse
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      bearerFormat: API key