LeadGenius Records API

openapi: 3.1.0
info:
  title: LeadGenius Enrichment Campaigns Records API
  version: v1
  summary: RESTful API for B2B account and contact enrichment, contact append, exclusion lists and rapid (real-time) enrichment.
  description: 'The LeadGenius public API is a RESTful API that sends and receives records from the LeadGenius Dashboard product. Records are associated to Campaigns in Dashboard and consist of Accounts that can optionally include related Contact records. A Campaign can be created in Dashboard using the Dashboard Wizard or via the API; any Campaign in Dashboard can be accessed using the API.


    Two modes are offered. **Campaign (batch) enrichment** uploads records to a Campaign, LeadGenius enriches or appends contacts, and a webhook fires when records are finalized so they can be retrieved. **Rapid enrichment** submits a single account or contact (or a get_contacts request) for real-time enrichment and retrieves the enriched record by id.


    This description was captured by the API Evangelist enrichment pipeline from the published LeadGenius API reference at https://docs.leadgenius.com/ — LeadGenius does not publish a machine readable OpenAPI definition. Every path, method, parameter, field and error code below is transcribed from that reference and its Python/JavaScript/cURL samples.'
  termsOfService: https://www.leadgenius.com/legal/terms
  contact:
    name: LeadGenius Sales
    email: sales@leadgenius.com
    url: https://docs.leadgenius.com/
servers:
- url: https://leadgenius.com
  description: Production
security:
- TokenAuth: []
tags:
- name: Records
  description: Upload records to a campaign and retrieve enriched results.
paths:
  /api/v1/enrichment/upload/{slug}/:
    parameters:
    - $ref: '#/components/parameters/CampaignSlug'
    get:
      tags:
      - Records
      operationId: getUploadRequestSample
      summary: Get the upload request sample for a campaign
      description: Returns a sample upload payload for the campaign, describing the field names and campaign identifier needed to send records correctly.
      responses:
        '200':
          description: Sample upload request for the campaign.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordUploadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags:
      - Records
      operationId: uploadRecordsToCampaign
      summary: Upload records to a campaign
      description: Upload up to 200 Account and/or Contact records per request to the campaign for enrichment or contact append.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecordUploadRequest'
      responses:
        '200':
          description: Records accepted for enrichment.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/enrichment/retrieve/{slug}/:
    parameters:
    - $ref: '#/components/parameters/CampaignSlug'
    get:
      tags:
      - Records
      operationId: retrieveCampaignRecords
      summary: Query campaign status and retrieve finalized records
      description: Query a running job to find out the status of an API campaign. If the campaign has been completed you receive the completed data. Results are paginated at 100 records.
      parameters:
      - name: id
        in: query
        required: false
        description: Return only the record(s) with the assigned ID. Repeat the parameter to request several ids (?id=1&id=2).
        schema:
          type: array
          items:
            type: integer
        style: form
        explode: true
      - name: finalized_from
        in: query
        required: false
        description: Filter records by date of finalization (from). Formats 2022-01-02 or 2022-01-03T18:03:11Z.
        schema:
          type: string
      - name: finalized_to
        in: query
        required: false
        description: Filter records by date of finalization (to). Formats 2022-01-02 or 2022-01-03T18:03:11Z.
        schema:
          type: string
      responses:
        '200':
          description: Campaign job status and, when completed, the finalized records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignRetrieveResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    RetrievedRecord:
      type: object
      properties:
        finalized:
          type: string
          description: The date the record was finalized.
        created:
          type: string
          description: The date the record was created.
        status:
          type: string
          description: The current status of the record.
          enum:
          - original
          - finalized_complete
          - finalized_incomplete
          - finalized_unenriched
          - finalized_cancelled
        data:
          $ref: '#/components/schemas/Record'
    Record:
      type: object
      description: An Account record, optionally carrying related Contact fields.
      properties:
        org_record_id:
          type: string
          description: The record ID of the company or account (e.g. your CRM account ID).
        org_company_name:
          type: string
          description: The name of the company.
        org_website:
          type: string
          description: The URL for the company's website.
        org_linkedin_url:
          type: string
          description: The URL of the company's LinkedIn profile.
        org_phone:
          type: string
          description: The main phone number of the company.
        org_street:
          type: string
        org_city:
          type: string
        org_state:
          type: string
        org_zip_code:
          type: string
        org_country:
          type: string
        org_industry:
          type: string
        org_num_employees:
          type: string
          description: The number of employees at the company, expressed as a range.
        org_num_employees_exact:
          type: integer
        org_annual_revenue:
          type: string
        contact_record_id:
          type: string
          description: The record ID of the contact (e.g. your CRM contact or lead ID).
        contact_first_name:
          type: string
        contact_last_name:
          type: string
        contact_email:
          type: string
        contact_job_title:
          type: string
        contact_linkedin_url:
          type: string
        contact_department:
          $ref: '#/components/schemas/Department'
        contact_seniority:
          type: string
          description: The contact's seniority level (C-Level, VP, Director, Manager, Senior, Entry Level).
    Error:
      type: object
      description: 'Django-REST-framework style validation envelope — a map of field name to an array of messages, e.g. {"type": ["This field is required."]}.'
      additionalProperties:
        type: array
        items:
          type: string
    RecordUploadRequest:
      type: object
      required:
      - slug
      - fields
      - records
      properties:
        slug:
          type: string
          description: Campaign slug/identifier.
        fields:
          type: array
          description: The field names to be enriched and returned.
          items:
            type: string
        type:
          type: string
          description: Upload type, e.g. datahub.
        records:
          type: array
          description: Up to 200 Account/Contact records per request.
          items:
            $ref: '#/components/schemas/Record'
    CampaignRetrieveResponse:
      type: object
      properties:
        status:
          type: string
          description: Job status.
          enum:
          - Completed
          - In-Progress
        records:
          type: array
          items:
            $ref: '#/components/schemas/RetrievedRecord'
    Department:
      type: string
      description: Contact department selector.
      enum:
      - Business Development
      - Consulting
      - Design
      - Education
      - Engineering
      - Executive
      - Finance
      - Health Services
      - Human Resources
      - Information Technology
      - Legal
      - Marketing
      - Media and Communications
      - Operations
      - Product
      - Sales
  responses:
    NotFound:
      description: Not Found -- The specified resource could not be found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized -- Your API key is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad Request -- Your request is invalid in some way.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Too Many Requests -- You're exceeding your rate-limits (50 requests per minute).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal Server Error -- We had a problem with our server. Try again later.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    CampaignSlug:
      name: slug
      in: path
      required: true
      description: Campaign slug/identifier on the LeadGenius platform.
      schema:
        type: string
  securitySchemes:
    TokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'LeadGenius uses API keys. Include the key in every request as `Authorization: Token {apikey}`.'