Ometria Field forget (email / phone erasure) API

openapi: 3.2.0
info:
  version: 1.1.0
  title: Ometria data Field forget (email / phone erasure) API
  description: 'Welcome to the Ometria API reference.


    The Ometria API is organized around the REST methodology, and it uses resource-oriented URLs, and common HTTP response codes to indicate API errors. All requests are authenticated using an API key which can be obtained from your account settings.


    ### HTTPS


    All requests to the Ometria API MUST be carried out via HTTPS. API servers do not listen on unsecured HTTP ports to avoid the possibility of insecure information exchange.


    ### Message encoding


    The V2 Ometria API uses JSON encoding for all data exchanges and assumes UTF-8 character encoding throughout.


    ### Rate limits


    The Ometria API has a default rate limit of 4 requests per second per Ometria account. The /push/ endpoint allows 8 requests per second per Ometria account. If you expect to exceed this limit, please contact us.


    In the case of your application being rate limited, the HTTP code 429 (too many requests) will be returned. In this case your application should reduce the number of requests it is trying to send.'
  contact:
    name: Ometria
    email: support@ometria.com
    url: https://ometria.com
servers:
- url: https://api.ometria.com/v2
security:
- apikey: []
tags:
- name: Field forget (email / phone erasure)
paths:
  /field-forget:
    get:
      tags:
      - Field forget (email / phone erasure)
      summary: List field forget requests
      description: 'Returns previously filed field forget requests for your account and their status, newest first (by `timestamp_created`). Requests made from the Ometria app are included, with `source.origin` set to `app`.


        Page with `limit` and `offset`; `total_count` is the number of requests for the account.'
      parameters:
      - name: limit
        in: query
        description: The number of records to fetch. Maximum 500; larger values are capped to 500.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 500
          default: 100
      - name: offset
        in: query
        description: Index of first record to fetch.
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
      responses:
        '200':
          description: A page of field forget request objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldForgetRequestPage'
              example:
                requests:
                - id: 6f1c2a0e-3b7d-4c8a-9e21-5d0f7b8a4c13
                  profile_hash: 27f4-f0b281-00003039
                  status: pending
                  fields:
                  - email
                  source:
                    origin: api
                    api_request_id: 0b7d9c2e-4f61-4e0a-8c3d-2a9e5f7b1d64
                  timestamp_created: '2026-09-07T10:18:12.833949+00:00'
                  timestamp_completed: null
                - id: 2c7e9f1a-5b3d-4e8c-9a1f-6d4b2e8c0a35
                  profile_hash: 27f4-26e69b-0000007b
                  status: completed
                  fields:
                  - phone
                  source:
                    origin: app
                    api_request_id: null
                  timestamp_created: '2026-09-06T16:02:41.512087+00:00'
                  timestamp_completed: '2026-09-06T16:02:43.077120+00:00'
                offset: 0
                page_size: 2
                total_count: 2
        '403':
          description: API key is not authorised to access this resource.
      operationId: getFieldForget
      x-operation-id-source: derived
    post:
      tags:
      - Field forget (email / phone erasure)
      summary: Create new field forget request
      description: 'Erase a profile''s `email` and/or `phone` while keeping the rest of the profile. For each requested field, Ometria clears the value on the profile. Nothing prevents the same value being added back to this profile later either.


        `profile_hash` is the `id` of a profile, as returned by `GET /profiles/`.


        Requests are processed asynchronously. A `202` means the request was accepted and queued; poll `GET /field-forget/{id}` until `status` is terminal. A request identical to one that is still `pending` or `in_progress` and less than 24 hours old returns the existing request''s `id` (still `202`) rather than creating a new one, so retries are safe. Once a request has reached a terminal status, a new request for the same profile and fields is accepted again.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FieldForgetSubmission'
            examples:
              single_field:
                summary: Forget the email address only
                value:
                  profile_hash: 27f4-f0b281-00003039
                  fields:
                  - email
              both_fields:
                summary: Forget both the email address and the phone number
                value:
                  profile_hash: 27f4-f0b281-00003039
                  fields:
                  - email
                  - phone
        description: 'Provide the `profile_hash` of the profile and the `fields` to erase: `email`, `phone`, or both.'
        required: true
      responses:
        '202':
          description: Field forget request accepted and queued for processing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldForgetPostResponse'
        '400':
          description: Invalid payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldForgetErrorMessage'
              examples:
                fields_missing_or_empty:
                  summary: '`fields` missing, empty or not a list'
                  value:
                    message: fields must be a non-empty list
                    status: 400
                    title: Bad Request
                fields_unsupported:
                  summary: '`fields` contains an unsupported value'
                  value:
                    message: fields must be a subset of email, phone
                    status: 400
                    title: Bad Request
                profile_hash_malformed:
                  summary: '`profile_hash` missing, not lowercase, or not a valid profile hash'
                  value:
                    message: profile_hash is malformed
                    status: 400
                    title: Bad Request
        '403':
          description: API key is not authorised to access this resource.
        '404':
          description: Profile not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldForgetErrorMessage'
              example:
                message: Profile doesn't exist
                status: 404
                title: Resource Not Found
      operationId: postFieldForget
      x-operation-id-source: derived
  /field-forget/bulk:
    post:
      tags:
      - Field forget (email / phone erasure)
      summary: Create up to 100 field forget requests in one call
      description: 'Submit up to 100 field forget requests in a single call. Each item is judged and processed independently: a malformed item is rejected without blocking its siblings, and an item identical to a request still `pending` or `in_progress` and less than 24 hours old is reported as `duplicate` and returns that existing request''s `id`, rather than creating a new one.


        This always returns `202`, even when every item was rejected, so check each item''s `result` field rather than the HTTP status. For each accepted or duplicate item, poll `GET /field-forget/{id}` with its `id` to find out how the request completed.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FieldForgetBulkSubmission'
            example:
              requests:
              - profile_hash: 27f4-f0b281-00003039
                fields:
                - email
              - profile_hash: 27f4-26e69b-0000007b
                fields:
                - email
                - phone
        description: '`requests`: a non-empty list, capped at 100, of the same `profile_hash`/`fields` objects `POST /field-forget` accepts.'
        required: true
      responses:
        '202':
          description: Returns one result per submitted item.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldForgetBulkResponse'
              example:
                request_id: 0b7d9c2e-4f61-4e0a-8c3d-2a9e5f7b1d64
                accepted: 1
                duplicate: 1
                rejected: 1
                results:
                - index: 0
                  profile_hash: 27f4-f0b281-00003039
                  result: accepted
                  id: 6f1c2a0e-3b7d-4c8a-9e21-5d0f7b8a4c13
                - index: 1
                  profile_hash: 27f4-26e69b-0000007b
                  result: duplicate
                  id: 2c7e9f1a-5b3d-4e8c-9a1f-6d4b2e8c0a35
                - index: 2
                  profile_hash: null
                  result: rejected
                  id: null
                  message: profile_hash is malformed
        '400':
          description: 'The envelope itself is invalid: not an object, `requests` missing, empty, not a list, or over the 100-item cap. Malformed individual items are reported per-item in the `202` response instead.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldForgetErrorMessage'
              examples:
                requests_missing_or_empty:
                  summary: '`requests` missing, empty or not a list'
                  value:
                    message: requests must be a non-empty list
                    status: 400
                    title: Bad Request
                requests_over_cap:
                  summary: '`requests` has more than 100 items'
                  value:
                    message: requests must not exceed 100 items
                    status: 400
                    title: Bad Request
        '403':
          description: API key is not authorised to access this resource.
      operationId: postFieldForgetBulk
      x-operation-id-source: derived
  /field-forget/{id}:
    get:
      tags:
      - Field forget (email / phone erasure)
      summary: Get details of specific field forget request
      description: Returns details and status of a field forget request by its ID. Poll this endpoint after `POST /field-forget` until `status` is one of `completed`, `aborted_sole_identifier`, `not_found` or `failed`.
      parameters:
      - name: id
        in: path
        description: The request ID returned by `POST /field-forget`.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A field forget request object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldForgetRequest'
              examples:
                pending:
                  summary: Accepted, waiting to be processed
                  value:
                    id: 6f1c2a0e-3b7d-4c8a-9e21-5d0f7b8a4c13
                    profile_hash: 27f4-f0b281-00003039
                    status: pending
                    fields:
                    - email
                    source:
                      origin: api
                      api_request_id: 0b7d9c2e-4f61-4e0a-8c3d-2a9e5f7b1d64
                    timestamp_created: '2026-09-07T10:18:12.833949+00:00'
                    timestamp_completed: null
                completed:
                  summary: Field(s) erased
                  value:
                    id: 6f1c2a0e-3b7d-4c8a-9e21-5d0f7b8a4c13
                    profile_hash: 27f4-f0b281-00003039
                    status: completed
                    fields:
                    - email
                    source:
                      origin: api
                      api_request_id: 0b7d9c2e-4f61-4e0a-8c3d-2a9e5f7b1d64
                    timestamp_created: '2026-09-07T10:18:12.833949+00:00'
                    timestamp_completed: '2026-09-07T10:18:14.102331+00:00'
                aborted_sole_identifier:
                  summary: 'Refused: no other matchable identifier would remain'
                  value:
                    id: b3e8f1d2-7c4a-4a9e-8d5f-1e2c3b4a5d6e
                    profile_hash: 27f4-26e69b-0000007b
                    status: aborted_sole_identifier
                    fields:
                    - email
                    - phone
                    source:
                      origin: api
                      api_request_id: 5e9a1c3f-2d7b-4f60-a8e4-9c1b3d5f7a20
                    timestamp_created: '2026-09-07T09:40:03.221904+00:00'
                    timestamp_completed: '2026-09-07T09:40:04.006512+00:00'
                not_found:
                  summary: Profile did not exist when processed
                  value:
                    id: 9a2d4c6e-1f3b-4d5a-b7c8-0e1f2a3b4c5d
                    profile_hash: 27f4-8337f0-002384af
                    status: not_found
                    fields:
                    - phone
                    source:
                      origin: api
                      api_request_id: 7f3b9d1e-6a2c-4e8f-b0d5-3c7a9e1f5b82
                    timestamp_created: '2026-09-07T08:15:27.480013+00:00'
                    timestamp_completed: '2026-09-07T08:15:28.115760+00:00'
                failed:
                  summary: Processing error; resubmit to retry
                  value:
                    id: d4c3b2a1-0f9e-4d8c-b7a6-5e4f3d2c1b0a
                    profile_hash: 27f4-f0b281-00003039
                    status: failed
                    fields:
                    - email
                    source:
                      origin: api
                      api_request_id: 1c5e7a9b-3d2f-4b6c-8e0a-4f6d8b2c9e17
                    timestamp_created: '2026-09-06T22:03:11.905228+00:00'
                    timestamp_completed: '2026-09-06T22:03:13.372641+00:00'
        '400':
          description: The request ID is not a valid UUID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldForgetErrorMessage'
              example:
                message: Field forget request ID is invalid
                status: 400
                title: Bad Request
        '403':
          description: API key is not authorised to access this resource.
        '404':
          description: Field forget request with specified ID was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldForgetErrorMessage'
              example:
                message: Field forget request doesn't exist
                status: 404
                title: Resource Not Found
      operationId: getFieldForgetById
      x-operation-id-source: derived
components:
  schemas:
    FieldForgetBulkResponse:
      type: object
      description: 'The outcome of a bulk field forget submission: one result per submitted item, plus counts by outcome.'
      properties:
        request_id:
          type: string
          description: Identifies this `POST /field-forget/bulk` call. If you sent an `X-Request-ID` header on the call, this is its value, so you can correlate it with your own logs; otherwise Ometria generates one.
        accepted:
          type: integer
          description: Number of items that created a new request.
        duplicate:
          type: integer
          description: Number of items that matched a request already `pending` or `in_progress` and less than 24 hours old.
        rejected:
          type: integer
          description: Number of items that failed validation and created no request.
        results:
          type: array
          description: One entry per submitted item, in the same order as submitted.
          items:
            $ref: '#/components/schemas/FieldForgetBulkResult'
      example:
        request_id: 0b7d9c2e-4f61-4e0a-8c3d-2a9e5f7b1d64
        accepted: 1
        duplicate: 1
        rejected: 1
        results:
        - index: 0
          profile_hash: 27f4-f0b281-00003039
          result: accepted
          id: 6f1c2a0e-3b7d-4c8a-9e21-5d0f7b8a4c13
        - index: 1
          profile_hash: 27f4-26e69b-0000007b
          result: duplicate
          id: 2c7e9f1a-5b3d-4e8c-9a1f-6d4b2e8c0a35
        - index: 2
          profile_hash: null
          result: rejected
          id: null
          message: profile_hash is malformed
    FieldForgetRequestPage:
      type: object
      description: A page of field forget requests.
      properties:
        requests:
          type: array
          description: The list of paginated objects.
          items:
            $ref: '#/components/schemas/FieldForgetRequest'
        offset:
          type: integer
          description: The offset value applied for pagination.
          example: 0
        page_size:
          type: integer
          description: The actual number of objects in the current page.
          example: 2
        total_count:
          type: integer
          description: The total number of field forget requests for the account.
          example: 2
    FieldForgetRequest:
      type: object
      description: Describes a field forget request and its status
      properties:
        id:
          type: string
          description: The request ID
        profile_hash:
          type: string
          description: The profile hash of the profile the request was filed for (eg 27f4-f0b281-00003039).
        status:
          type: string
          description: 'Current state of the request. `pending`: accepted and queued. `in_progress`: being processed. Terminal states: `completed` (the requested fields were erased), `aborted_sole_identifier` (refused and nothing changed, because erasing the fields would have left the profile with no other identifier Ometria can match on), `not_found` (the profile did not exist when processed), `failed` (an error occurred; resubmit to retry).'
          enum:
          - pending
          - in_progress
          - completed
          - aborted_sole_identifier
          - failed
          - not_found
        fields:
          type: array
          description: The fields requested, sorted alphabetically and deduplicated.
          items:
            type: string
            description: A field that can be forgotten. This list is the set supported by the service and is kept in sync via the service's own spec test.
            enum:
            - email
            - phone
        source:
          type: object
          description: Where the request originated.
          properties:
            origin:
              type: string
              description: '`api` for requests filed through this API, `app` for requests filed from the Ometria app.'
              enum:
              - app
              - api
            api_request_id:
              type:
              - string
              - 'null'
              description: Identifies the `POST /field-forget` call that filed this request. If you sent an `X-Request-ID` header on that call, this is its value, so you can correlate the request with your own logs; otherwise Ometria generates one. `null` for requests filed from the Ometria app.
        timestamp_created:
          type: string
          description: Date and time of request being filed. Following ISO 8601 dateTime format with timezone offset _YYYY-MM-DDThh:mm:ss+Z_.
          format: date-time
        timestamp_completed:
          type:
          - string
          - 'null'
          description: Date and time of request reaching a terminal status. Following ISO 8601 dateTime format with timezone offset _YYYY-MM-DDThh:mm:ss+Z_. `null` while the request is `pending` or `in_progress`.
          format: date-time
      example:
        id: 6f1c2a0e-3b7d-4c8a-9e21-5d0f7b8a4c13
        profile_hash: 27f4-f0b281-00003039
        status: completed
        fields:
        - email
        source:
          origin: api
          api_request_id: 0b7d9c2e-4f61-4e0a-8c3d-2a9e5f7b1d64
        timestamp_created: '2026-09-07T10:18:12.833949+00:00'
        timestamp_completed: '2026-09-07T10:18:14.102331+00:00'
    FieldForgetSubmission:
      type: object
      description: Field forget request submission. Identifies one profile by its `profile_hash` and names the field(s) to erase.
      required:
      - profile_hash
      - fields
      properties:
        profile_hash:
          type: string
          description: The profile hash of the profile to act on, as returned by `GET /profiles/`.
          pattern: ^[0-9a-f]+-[0-9a-f]{6}-[0-9a-f]{8,}$
          example: 27f4-f0b281-00003039
        fields:
          type: array
          description: 'The field(s) to erase: `email`, `phone`, or both. Order does not matter and duplicates are ignored; the request is stored and returned with the fields sorted alphabetically.'
          minItems: 1
          items:
            type: string
            description: A field that can be forgotten. This list is the set supported by the service and is kept in sync via the service's own spec test.
            enum:
            - email
            - phone
      example:
        profile_hash: 27f4-f0b281-00003039
        fields:
        - email
    FieldForgetBulkResult:
      type: object
      description: The outcome of one item from a bulk field forget submission.
      properties:
        index:
          type: integer
          description: Position of this item in the submitted `requests` array.
        profile_hash:
          type:
          - string
          - 'null'
          description: Echoed only when the submitted value was actually a string.
        result:
          type: string
          description: '`accepted`: a new request was created. `duplicate`: matched a request already `pending` or `in_progress` and less than 24 hours old; `id` is that existing request. `rejected`: the item failed validation and no request was created.'
          enum:
          - accepted
          - duplicate
          - rejected
        id:
          type:
          - string
          - 'null'
          description: The request ID. Use it with `GET /field-forget/{id}` to poll for the outcome. `null` for a `rejected` item, which created no request.
        message:
          type: string
          description: 'Present only when `result` is `rejected`: what was wrong with this item.'
    FieldForgetErrorMessage:
      type: object
      description: Error returned by the field forget endpoints.
      properties:
        message:
          type: string
          description: What was wrong with the request.
        status:
          type: integer
          description: The HTTP status code.
        title:
          type: string
          description: Short description of the error class.
      example:
        message: fields must be a subset of email, phone
        status: 400
        title: Bad Request
    FieldForgetBulkSubmission:
      type: object
      description: A batch of field forget request submissions.
      required:
      - requests
      properties:
        requests:
          type: array
          description: A non-empty list, capped at 100 items, of `profile_hash`/`fields` objects, each with the same shape `POST /field-forget` accepts.
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/FieldForgetSubmission'
    FieldForgetPostResponse:
      type: object
      description: Response to a field forget request submission
      properties:
        id:
          type: string
          description: The request ID. Use it with `GET /field-forget/{id}` to poll for the outcome. An identical request that is still in flight and less than 24 hours old returns the ID of the existing request.
      example:
        id: 6f1c2a0e-3b7d-4c8a-9e21-5d0f7b8a4c13
  securitySchemes:
    apikey:
      type: apiKey
      name: X-Ometria-Auth
      in: header
      description: Ometria API key which can be obtained from your Ometria account administrator
    apiKeyReadTranslations:
      type: apiKey
      name: X-Ometria-Auth
      in: header
      description: 'Ometria API key which can be obtained from your Ometria account administrator. **Note**: The API key must have the scope `read:translations`.'
    apiKeyWriteTranslations:
      type: apiKey
      name: X-Ometria-Auth
      in: header
      description: 'Ometria API key which can be obtained from your Ometria account administrator. **Note**: The API key must have the scope `write:translations`.'
x-explorer-enabled: false
x-readme:
  proxy-enabled: true
  samples-enabled: true