openapi: 3.1.0
info:
  title: UserGems API
  description: |
    The UserGems API lets customers programmatically add contacts to track for job
    changes and add accounts to receive prospects for. It also exposes a privacy
    delete endpoint used to honor data-subject removal requests. Requests are
    authenticated with a customer-issued API key sent in the X-Api-Key header and
    are processed asynchronously — responses confirm enqueueing, not completion.
  version: "1.0.0"
  contact:
    name: UserGems
    url: https://www.usergems.com
    email: support@usergems.com
  license:
    name: UserGems Terms of Service
    url: https://www.usergems.com/legal/terms
servers:
  - url: https://api.usergems.com/v1
    description: Production
security:
  - ApiKeyAuth: []

tags:
  - name: Contacts
    description: Add and remove contacts UserGems should track for job changes.
  - name: Accounts
    description: Add and remove accounts UserGems should source prospects against.
  - name: Privacy
    description: Honor data-subject deletion requests for tracked contacts.

paths:
  /contact:
    post:
      summary: Add Contact
      description: |
        Enqueue a contact for UserGems to track for job changes. The contact is
        identified by email; optional fields enrich the tracked record with name,
        company, LinkedIn URL, relationship type, signal label, and up to 100
        custom signal fields. The API returns immediately once the contact is
        accepted into the processing queue.
      operationId: addContact
      tags:
        - Contacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddContactRequest'
            examples:
              AddContactExample:
                $ref: '#/components/examples/AddContactExample'
      responses:
        '200':
          description: Contact added to the processing queue.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueueAck'
              examples:
                AddContactAck:
                  $ref: '#/components/examples/AddContactAck'
        '4XX':
          $ref: '#/components/responses/ErrorResponse'
        '5XX':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      summary: Delete Contact
      description: |
        Remove a contact from UserGems' tracked list. The contact is identified
        by email; relationshipType and signal narrow the deletion to a specific
        scope so the same email can remain tracked under other relationship or
        signal combinations.
      operationId: deleteContact
      tags:
        - Contacts
      parameters:
        - name: email
          in: query
          required: true
          description: Email address of the contact to remove.
          schema:
            type: string
            format: email
        - name: relationshipType
          in: query
          required: false
          description: Restrict deletion to a single relationship type bucket.
          schema:
            type: string
        - name: signal
          in: query
          required: false
          description: Restrict deletion to a single signal label.
          schema:
            type: string
      responses:
        '200':
          description: Contact deleted from the tracked list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueueAck'
              examples:
                DeleteContactAck:
                  $ref: '#/components/examples/DeleteContactAck'
        '4XX':
          $ref: '#/components/responses/ErrorResponse'
        '5XX':
          $ref: '#/components/responses/ErrorResponse'

  /account:
    post:
      summary: Add Account
      description: |
        Enqueue an account so UserGems sources prospects against it. Accounts are
        identified by the (name, domain) pair; optional fields associate the
        account with a Salesforce ID, a custom ID, a report name, and a signal
        label so prospects can be routed back to the right workflow.
      operationId: addAccount
      tags:
        - Accounts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddAccountRequest'
            examples:
              AddAccountExample:
                $ref: '#/components/examples/AddAccountExample'
      responses:
        '200':
          description: Account added.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueueAck'
              examples:
                AddAccountAck:
                  $ref: '#/components/examples/AddAccountAck'
        '4XX':
          $ref: '#/components/responses/ErrorResponse'
        '5XX':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      summary: Delete Account
      description: |
        Remove a previously added account. Identified by (name, domain); the
        optional reportName, signal, salesforceId, and customId fields scope the
        deletion to a specific routing context.
      operationId: deleteAccount
      tags:
        - Accounts
      parameters:
        - name: name
          in: query
          required: true
          description: Account name as previously submitted.
          schema:
            type: string
        - name: domain
          in: query
          required: true
          description: Primary domain for the account.
          schema:
            type: string
        - name: reportName
          in: query
          required: false
          description: Report or workflow grouping the account belongs to.
          schema:
            type: string
        - name: signal
          in: query
          required: false
          description: Signal label originally attached to the account.
          schema:
            type: string
        - name: salesforceId
          in: query
          required: false
          description: Salesforce Account ID for cross-reference.
          schema:
            type: string
        - name: customId
          in: query
          required: false
          description: Customer-supplied identifier for cross-reference.
          schema:
            type: string
      responses:
        '200':
          description: Account deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueueAck'
              examples:
                DeleteAccountAck:
                  $ref: '#/components/examples/DeleteAccountAck'
        '4XX':
          $ref: '#/components/responses/ErrorResponse'
        '5XX':
          $ref: '#/components/responses/ErrorResponse'

  /privacy/delete:
    post:
      summary: Privacy Delete
      description: |
        Honor a data-subject deletion request. Removes the contact identified by
        email from all UserGems tracking surfaces. Designed to satisfy GDPR and
        CCPA right-to-erasure obligations.
      operationId: privacyDelete
      tags:
        - Privacy
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrivacyDeleteRequest'
            examples:
              PrivacyDeleteExample:
                $ref: '#/components/examples/PrivacyDeleteExample'
      responses:
        '200':
          description: Contact removed from UserGems systems.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueueAck'
              examples:
                PrivacyDeleteAck:
                  $ref: '#/components/examples/PrivacyDeleteAck'
        '4XX':
          $ref: '#/components/responses/ErrorResponse'
        '5XX':
          $ref: '#/components/responses/ErrorResponse'

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: |
        Customer-issued API key. Request a key from support@usergems.com. The
        key must be included on every request in the X-Api-Key header.

  schemas:
    AddContactRequest:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          format: email
          description: Email address of the person UserGems should track.
        firstName:
          type: string
          description: Given name of the contact.
        lastName:
          type: string
          description: Family name of the contact.
        fullName:
          type: string
          description: Full display name; an alternative to firstName + lastName.
        company:
          type: string
          description: Current employer at time of submission.
        relationshipType:
          type: string
          description: |
            Bucket the contact belongs to. Common values include Champion, User,
            Prospect, and Other. Customers can define additional custom values.
          examples:
            - Champion
            - User
            - Prospect
            - Other
        linkedinUrl:
          type: string
          format: uri
          description: Public LinkedIn profile URL for the contact.
        signal:
          type: string
          description: Signal label associating the contact with a workflow.
        custom:
          type: string
          description: Free-form custom metadata to round-trip with downstream events.
      additionalProperties:
        type: string
        description: |
          Customers can attach up to 100 custom signal fields as additional
          top-level string properties.

    AddAccountRequest:
      type: object
      required:
        - name
        - domain
      properties:
        name:
          type: string
          description: Account name (display name of the target company).
        domain:
          type: string
          description: Primary domain for the target company (e.g. example.com).
        reportName:
          type: string
          description: Report or workflow grouping the account belongs to.
        signal:
          type: string
          description: Signal label to associate with prospects routed for this account.
        salesforceId:
          type: string
          description: Salesforce Account ID for cross-reference.
        customId:
          type: string
          description: Customer-supplied identifier for cross-reference.
        custom:
          type: string
          description: Free-form custom metadata to round-trip with downstream events.

    PrivacyDeleteRequest:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          format: email
          description: Email address of the data subject whose record must be removed.

    QueueAck:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: Human-readable confirmation message.

    Error:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: Human-readable error message.
        code:
          type: string
          description: Optional machine-readable error code.

  responses:
    ErrorResponse:
      description: Error response. UserGems returns standard HTTP status codes (400, 401, 403, 404, 405, 406, 410, 429, 500, 503).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  examples:
    AddContactExample:
      summary: Add a Champion contact
      value:
        email: jane.doe@example.com
        firstName: Jane
        lastName: Doe
        company: Acme Inc
        relationshipType: Champion
        linkedinUrl: https://www.linkedin.com/in/janedoe
        signal: q2-champions
    AddContactAck:
      summary: Contact accepted
      value:
        message: Contact added to queue
    DeleteContactAck:
      summary: Contact removed
      value:
        message: Contact deleted
    AddAccountExample:
      summary: Add a target account
      value:
        name: Acme Inc
        domain: acme.com
        reportName: Q2-Enterprise-ICP
        signal: hiring-vp-sales
        salesforceId: 0014x00000ABCDeAAA
    AddAccountAck:
      summary: Account accepted
      value:
        message: Account added
    DeleteAccountAck:
      summary: Account removed
      value:
        message: Account deleted
    PrivacyDeleteExample:
      summary: Honor a right-to-erasure request
      value:
        email: jane.doe@example.com
    PrivacyDeleteAck:
      summary: Contact removed for privacy
      value:
        message: Contact removed