openapi: 3.0.3
info:
  title: 'GenPage External API Documentation'
  description: ''
  version: 1.0.0
servers:
  -
    url: 'http://127.0.0.1:8000'
tags:
  -
    name: Audiences
    description: ''
  -
    name: Authentication
    description: ''
  -
    name: Campaigns
    description: ''
  -
    name: Endpoints
    description: ''
  -
    name: Leads
    description: ''
components:
  securitySchemes:
    default:
      type: apiKey
      name: Authorization
      in: header
      description: null
security:
  -
    default: []
paths:
  /api/external/v1/audiences/get-list:
    get:
      summary: 'Get the list of audiences.'
      operationId: getTheListOfAudiences
      description: 'This endpoint is used to get the list of audiences.'
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  audiences:
                    -
                      id: 1
                      name: 'Default Audience'
                properties:
                  audiences:
                    type: array
                    example:
                      -
                        id: 1
                        name: 'Default Audience'
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        name:
                          type: string
                          example: 'Default Audience'
        401:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
      tags:
        - Audiences
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                workspace_id:
                  type: integer
                  description: ''
                  example: 16
                  nullable: false
              required:
                - workspace_id
  /api/external/v1/generate-api-token:
    post:
      summary: 'Generate an API token. Should be done from the GenPage dashboard.'
      operationId: generateAnAPITokenShouldBeDoneFromTheGenPageDashboard
      description: 'This endpoint returns the generated token to be used in the external integration.'
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  token: 'Bearer <Bearer token>'
                properties:
                  token:
                    type: string
                    example: 'Bearer <Bearer token>'
        401:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: 'Must be at least 2 characters. Must not be greater than 255 characters.'
                  example: b
                  nullable: false
                workspace_id:
                  type: integer
                  description: ''
                  example: 16
                  nullable: false
              required:
                - name
                - workspace_id
  /api/external/v1/hello-world:
    get:
      summary: 'Test authentication endpoint.'
      operationId: testAuthenticationEndpoint
      description: 'This endpoint is used to test the authentication.'
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Hello World'
                properties:
                  message:
                    type: string
                    example: 'Hello World'
        401:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
      tags:
        - Authentication
  /api/external/v1/campaigns/get-list:
    get:
      summary: 'Get the list of campaigns.'
      operationId: getTheListOfCampaigns
      description: 'This endpoint is used to get the list of campaigns.'
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  campaigns:
                    -
                      id: 1
                      name: 'Test Campaign 1'
                      slug: test-campaign-1
                    -
                      id: 2
                      name: 'Saas Outreach'
                      slug: saas-outreach
                properties:
                  campaigns:
                    type: array
                    example:
                      -
                        id: 1
                        name: 'Test Campaign 1'
                        slug: test-campaign-1
                      -
                        id: 2
                        name: 'Saas Outreach'
                        slug: saas-outreach
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        name:
                          type: string
                          example: 'Test Campaign 1'
                        slug:
                          type: string
                          example: test-campaign-1
        401:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
      tags:
        - Campaigns
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                workspace_id:
                  type: integer
                  description: ''
                  example: 16
                  nullable: false
              required:
                - workspace_id
  /api/external/v1/get-api-tokens:
    get:
      summary: ''
      operationId: getApiExternalV1GetApiTokens
      description: ''
      parameters: []
      responses: {  }
      tags:
        - Endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                workspace_id:
                  type: integer
                  description: ''
                  example: 16
                  nullable: false
              required:
                - workspace_id
  /api/external/v1/delete-api-token:
    delete:
      summary: ''
      operationId: deleteApiExternalV1DeleteApiToken
      description: ''
      parameters: []
      responses: {  }
      tags:
        - Endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                token_id:
                  type: string
                  description: ''
                  example: architecto
                  nullable: false
              required:
                - token_id
  /api/external/v1/leads/upsert-leads:
    post:
      summary: 'Upsert leads.'
      operationId: upsertLeads
      description: "This endpoint is used to upsert (update or insert) leads.\n\nThe leads are sent in the request body.\nThe leads are an array of objects.\nThe leads.*.values are key/value pairs with the values of the lead.\n\n---\n### Required fields for creating or updating a lead\n\n**To create a new lead, at least one of:**\n- `email`\n- `linkedin_profile_url`\n\n**To update an existing lead, at least one of:**\n- `lead_id` (GenPage Lead ID)\n- `genpage_url` (GenPage URL)\n\n---\n### Optional but strongly recommended fields\n- `first_name`\n- `company_name`\n- `company_domain`\n---\n\nThe response is the job ID.\n\nThe job ID can be used to get the status of the job, and get all the leads that were upserted by this request."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  job_id: '1234567890'
                properties:
                  job_id:
                    type: string
                    example: '1234567890'
        401:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
      tags:
        - Leads
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                from:
                  type: string
                  description: 'The service that is sending the leads, use your own company/service name please.'
                  example: MyCompanyName
                  nullable: false
                campaign_id:
                  type: integer
                  description: 'The campaign ID to add the leads to.'
                  example: 1
                  nullable: false
                audience_id:
                  type: integer
                  description: 'The audience ID to add the leads to.'
                  example: 1
                  nullable: false
                leads:
                  type: array
                  description: 'Array of lead objects to upsert.'
                  example:
                    -
                      lead_id: 16
                      genpage_url: 'https://myworkspace.genpa.ge/aws-john'
                      values:
                        first_name: John
                        email: john@aws.com
                        company_name: 'Amazon Web Services'
                        linkedin_profile_url: 'https://www.linkedin.com/in/john-doe-1234567890'
                  items:
                    type: string
              required:
                - from
                - campaign_id
                - audience_id
                - leads
  /api/external/v1/leads/get-status:
    get:
      summary: 'Get the status of the job.'
      operationId: getTheStatusOfTheJob
      description: "This endpoint is used to get the status of the job.\nOnce the job is completed, the status will be \"completed\".\n\nThe status can be:\n- pending\n- completed\n- failed\n\nOnce the job is completed, please use the getLeads endpoint to get all the leads that were upserted by this request."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  status: pending
                  processed_rows: 10
                  total_rows: 100
                properties:
                  status:
                    type: string
                    example: pending
                  processed_rows:
                    type: integer
                    example: 10
                  total_rows:
                    type: integer
                    example: 100
        401:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
      tags:
        - Leads
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                job_id:
                  type: string
                  description: ''
                  example: architecto
                  nullable: false
              required:
                - job_id
  /api/external/v1/leads/get-leads:
    get:
      summary: 'Get the leads that were upserted by a job.'
      operationId: getTheLeadsThatWereUpsertedByAJob
      description: 'This endpoint is used to get the leads that were upserted by a job.'
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  leads:
                    -
                      lead_id: 56789
                      workspace_id: 222
                      campaign_id: 333
                      job_id: '1234567890'
                      values:
                        name: 'John Doe'
                        email: john@aws.com
                        company_name: AWS
                        url_slug: aws-john
                        logo: 'https://aws.com/logo.png'
                        logo_color: '#000000'
                        genpage_url: 'https://myworkspace.genpa.ge/aws-john'
                properties:
                  leads:
                    type: array
                    example:
                      -
                        lead_id: 56789
                        workspace_id: 222
                        campaign_id: 333
                        job_id: '1234567890'
                        values:
                          name: 'John Doe'
                          email: john@aws.com
                          company_name: AWS
                          url_slug: aws-john
                          logo: 'https://aws.com/logo.png'
                          logo_color: '#000000'
                          genpage_url: 'https://myworkspace.genpa.ge/aws-john'
                    items:
                      type: object
                      properties:
                        lead_id:
                          type: integer
                          example: 56789
                        workspace_id:
                          type: integer
                          example: 222
                        campaign_id:
                          type: integer
                          example: 333
                        job_id:
                          type: string
                          example: '1234567890'
                        values:
                          type: object
                          properties:
                            name:
                              type: string
                              example: 'John Doe'
                            email:
                              type: string
                              example: john@aws.com
                            company_name:
                              type: string
                              example: AWS
                            url_slug:
                              type: string
                              example: aws-john
                            logo:
                              type: string
                              example: 'https://aws.com/logo.png'
                            logo_color:
                              type: string
                              example: '#000000'
                            genpage_url:
                              type: string
                              example: 'https://myworkspace.genpa.ge/aws-john'
        401:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
      tags:
        - Leads
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                workspace_id:
                  type: integer
                  description: ''
                  example: 16
                  nullable: false
                job_id:
                  type: string
                  description: ''
                  example: architecto
                  nullable: false
              required:
                - workspace_id
                - job_id
