Oneprofile Referral API

openapi: 3.2.0
info:
  contact:
    email: support@getoneprofile.ai
    name: Oneprofile Support
  description: REST API reference for Oneprofile, the GTM data layer for your CRM. Manage tables, enrichments, and integrations. Authenticate with an API key to get started.
  termsOfService: https://www.getoneprofile.ai/terms
  title: Reference | Oneprofile Referral API
  version: 1.0.42765316646
tags:
- description: 'Endpoints for the workspace referral program: the shareable link, the friends who joined through it, and claiming a code after signup.'
  name: Referral
paths:
  /referrals/:
    get:
      description: The friends who joined through this workspace's link, newest first.
      operationId: list_referrals
      parameters:
      - in: query
        name: filters
        required: true
        schema:
          $ref: '#/components/schemas/ListReferralsFilterParamsSchema'
      - description: The number of items to return.
        in: query
        name: limit
        required: false
        schema:
          default: 10
          description: The number of items to return.
          maximum: 100
          minimum: 1
          title: Limit
          type: integer
      - in: query
        name: order_by
        required: false
        schema:
          $ref: '#/components/schemas/OrderingParametersForIdSignedUpAtCreatedAt'
          default: signed_up_at
          enum:
          - id
          - signed_up_at
          - created_at
          type: string
      - in: query
        name: order_direction
        required: false
        schema:
          default: desc
          enum:
          - asc
          - desc
          title: Order Direction
          type: string
      - description: Set the cursor to the next or previous page. You can get the cursor from the previous page's response.
        in: query
        name: cursor
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Set the cursor to the next or previous page. You can get the cursor from the previous page's response.
          title: Cursor for pagination.
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse_ReferralReadSchema_'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Forbidden
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Invalid request made to the API.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Internal server error.
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Bad gateway error.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Service unavailable.
      security:
      - APIKeyHeader: []
      - HTTPBearer: []
      summary: List referrals
      tags:
      - Referral
  /referrals/claim/:
    post:
      description: 'Attribute the caller''s workspace to a referral code and pay the signup rewards. Safe to call repeatedly and never an error: a code that does not apply reports `attributed: false`. Requires a signed-in user rather than an API key: the claim records who signed up, and an API key has no person behind it. Pass `dry_run=true` to see what the claim would answer without recording it.'
      operationId: claim_referral
      parameters:
      - description: Report what the claim would do, and record nothing.
        in: query
        name: dry_run
        required: false
        schema:
          default: false
          description: Report what the claim would do, and record nothing.
          title: Dry Run
          type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReferralClaimRequestSchema'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReferralClaimReadSchema'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Forbidden
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Invalid request made to the API.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Internal server error.
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Bad gateway error.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Service unavailable.
      security:
      - APIKeyHeader: []
      - HTTPBearer: []
      summary: Claim a referral code
      tags:
      - Referral
  /referrals/length/:
    get:
      description: How many referrals match the filter. The list is cursor-paginated and therefore cannot report a total itself, but the page shows an exact 'N of M', so the count is its own read.
      operationId: get_referrals_count
      parameters:
      - description: Narrow to friends still on a free plan, or only those on a paid plan. The two are disjoint; omit for everything.
        in: query
        name: status
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/ReferralStatus'
          - type: 'null'
          description: Narrow to friends still on a free plan, or only those on a paid plan. The two are disjoint; omit for everything.
          title: Status
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReferralCountSchema'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Forbidden
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Invalid request made to the API.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Internal server error.
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Bad gateway error.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Service unavailable.
      security:
      - APIKeyHeader: []
      - HTTPBearer: []
      summary: Count referrals
      tags:
      - Referral
  /referrals/program/:
    get:
      description: 'What the program pays, for the signup page. Deliberately unauthenticated: the person who most needs to see it has no account yet. It returns the two amounts and nothing else: resolving a code to the workspace behind it would turn this into a way to enumerate customer names.'
      operationId: get_referral_program
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReferralProgramReadSchema'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Forbidden
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Invalid request made to the API.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Internal server error.
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Bad gateway error.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Service unavailable.
      summary: Get the referral program's reward amounts
      tags:
      - Referral
  /referrals/summary/:
    get:
      description: The workspace's shareable referral link, the three headline counts, and the reward amounts the explainer copy quotes. The referral code is minted on first read, so a workspace that never opens the page never gets one.
      operationId: get_referral_summary
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReferralSummaryReadSchema'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Forbidden
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Invalid request made to the API.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Internal server error.
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Bad gateway error.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Service unavailable.
      security:
      - APIKeyHeader: []
      - HTTPBearer: []
      summary: Get the workspace's referral summary
      tags:
      - Referral
components:
  schemas:
    ForbiddenResponse:
      properties:
        detail:
          description: The detail of why the request is forbidden.
          title: Detail
          type: string
      required:
      - detail
      title: ForbiddenResponse
      type: object
    UnauthorizedResponse:
      properties:
        detail:
          description: The detail of why the request is unauthorized.
          title: Detail
          type: string
      required:
      - detail
      title: UnauthorizedResponse
      type: object
    ReferralStatus:
      description: 'How far along one referral is: the list filter''s vocabulary.


        Deliberately NOT Clay''s "lead" / "conversion". This product has a Find

        Leads feature, so a referral labelled a lead reads as a sales prospect.'
      enum:
      - signed_up
      - converted
      title: ReferralStatus
      type: string
    UnprocessableEntityIssue:
      properties:
        input:
          anyOf:
          - type: string
          - type: integer
          - type: number
          - type: boolean
          - items: {}
            type: array
          - additionalProperties: true
            type: object
          description: The user's input that caused the error.
          title: Input
        loc:
          description: The location of the error. Always contains 1 or 2 elements. The first element is the type of location (e.g. 'body', 'query', 'path', 'header'). The second element is the name of the field that caused the error. If the error is not related to a specific field, the second element is not present.
          items:
            type: string
          title: Loc
          type: array
        msg:
          description: The message of the error. The error message to show to the user.
          title: Msg
          type: string
        type:
          description: The type of the error. Useful for frontend code to handle different types of errors.
          title: Type
          type: string
      required:
      - loc
      - msg
      - type
      - input
      title: UnprocessableEntityIssue
      type: object
    ServerErrorResponse:
      properties:
        detail:
          description: The detail of why the server returned an error.
          title: Detail
          type: string
      required:
      - detail
      title: ServerErrorResponse
      type: object
    ReferralSummaryReadSchema:
      description: Everything the referrals page needs before it lists anything.
      properties:
        code:
          description: The workspace's permanent referral code.
          title: Code
          type: string
        conversion_reward_credits:
          description: Whole credits paid to BOTH sides when a referred workspace starts its first paid plan. Signing up pays nothing.
          title: Conversion Reward Credits
          type: integer
        link:
          description: The full URL to share. Assembled server-side so the client never has to know which domain the program currently points at.
          title: Link
          type: string
        stats:
          $ref: '#/components/schemas/ReferralStatsSchema'
      required:
      - code
      - link
      - stats
      - conversion_reward_credits
      title: ReferralSummaryReadSchema
      type: object
    ReferralProgramReadSchema:
      description: 'What the program pays. The public half of the referrals API.


        Everything else about a referral is workspace-private; these two numbers

        are the offer itself, and the person who most needs to read them (someone

        on the signup page holding a friend''s link) has no account yet.'
      properties:
        conversion_reward_credits:
          description: Whole credits paid to BOTH sides when a referred workspace starts its first paid plan. Signing up pays nothing.
          title: Conversion Reward Credits
          type: integer
      required:
      - conversion_reward_credits
      title: ReferralProgramReadSchema
      type: object
    ReferralStatsSchema:
      description: The three headline numbers on the referrals page.
      properties:
        converted_count:
          description: How many of them are on a paid plan.
          title: Converted Count
          type: integer
        credits_earned:
          description: Credits this workspace has been paid by the referral program, in decimal credits. Summed from payouts actually granted, so it never disagrees with the balance.
          title: Credits Earned
          type: number
        signed_up_count:
          description: 'How many friends have joined through the link, in total. Cumulative: it includes the ones who have since started paying.'
          title: Signed Up Count
          type: integer
      required:
      - signed_up_count
      - converted_count
      - credits_earned
      title: ReferralStatsSchema
      type: object
    PaginatedResponse_ReferralReadSchema_:
      properties:
        data:
          description: The list of ResponseItems.
          items:
            $ref: '#/components/schemas/ReferralReadSchema'
          title: Data
          type: array
        next_page_cursor:
          anyOf:
          - type: string
          - type: 'null'
          description: The cursor to the next page. If there are no more pages, this is None.
        previous_page_cursor:
          anyOf:
          - type: string
          - type: 'null'
          description: The cursor to the previous page. If there are no previous pages, this is None.
      title: PaginatedResponse[ReferralReadSchema]
      type: object
    ReferralCountSchema:
      description: How many referrals match the current filter.
      properties:
        count:
          title: Count
          type: integer
      required:
      - count
      title: ReferralCountSchema
      type: object
    ReferralClaimReadSchema:
      description: 'The outcome of a claim.


        Always 200. A code that does not apply (a reload, an existing customer

        clicking a colleague''s link) reports ``attributed: false`` rather than an

        error, because none of those are failures worth alarming a new user about.'
      properties:
        attributed:
          description: Whether the code was recorded against this workspace.
          title: Attributed
          type: boolean
        credits_on_upgrade:
          description: Whole credits this workspace will receive when it starts a paid plan; 0 when nothing was attributed. Signing up pays nothing, so this is the promise the welcome message makes.
          title: Credits On Upgrade
          type: integer
        referrer_name:
          anyOf:
          - type: string
          - type: 'null'
          description: The workspace that invited them, for the welcome message. Null on a dry run, which records nothing and so names nobody.
          title: Referrer Name
      required:
      - attributed
      - credits_on_upgrade
      - referrer_name
      title: ReferralClaimReadSchema
      type: object
    UnprocessableEntityResponse:
      properties:
        detail:
          description: The detail of the error. This is the error message to show to the user. You should also use the issues field to show more detailed error messages per field. Use this field for a single liner error message.
          title: Detail
          type: string
        issues:
          description: The issues that caused the error. There can be multiple issues. Each issue is a user-facing error message.
          items:
            $ref: '#/components/schemas/UnprocessableEntityIssue'
          title: Issues
          type: array
      required:
      - detail
      - issues
      title: UnprocessableEntityResponse
      type: object
    ListReferralsFilterParamsSchema:
      description: Query parameters for narrowing the referral list.
      properties:
        status:
          anyOf:
          - $ref: '#/components/schemas/ReferralStatus'
          - type: 'null'
          description: Narrow to friends still on a free plan, or only those on a paid plan. The two are disjoint; omit for everything.
      title: ListReferralsFilterParamsSchema
      type: object
    ReferralClaimRequestSchema:
      description: A referral code captured from the URL, offered up by a newly signed-up user.
      properties:
        code:
          description: The referral code as captured. Trimmed and normalized server-side.
          maxLength: 64
          minLength: 1
          title: Code
          type: string
        source:
          anyOf:
          - maxLength: 32
            type: string
          - type: 'null'
          description: 'The affiliate''s own tag for where the link was shared, banked at click time by the link redirect. Absent for a link followed any other way. Narrowed rather than validated server-side: an unrecognized value becomes untagged rather than failing a claim.'
          title: Source
      required:
      - code
      title: ReferralClaimRequestSchema
      type: object
    OrderingParametersForIdSignedUpAtCreatedAt:
      enum:
      - id
      - signed_up_at
      - created_at
      title: OrderingParametersForIdSignedUpAtCreatedAt
      type: string
    ReferralReadSchema:
      description: One row of the referral list.
      properties:
        converted_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          description: When they started their first paid plan; null while still on free.
          title: Converted At
        credits_earned:
          description: Credits this referral has earned the referrer, in decimal credits.
          title: Credits Earned
          type: number
        email:
          title: Email
          type: string
        id:
          format: uuid
          title: Id
          type: string
        name:
          anyOf:
          - type: string
          - type: 'null'
          description: The referred person's display name, when known.
          title: Name
        signed_up_at:
          description: When they joined through the link.
          format: date-time
          title: Signed Up At
          type: string
        status:
          $ref: '#/components/schemas/ReferralStatus'
      required:
      - id
      - name
      - email
      - signed_up_at
      - converted_at
      - status
      - credits_earned
      title: ReferralReadSchema
      type: object
  securitySchemes:
    APIKeyHeader:
      in: header
      name: X-API-Key
      type: apiKey
    HTTPBearer:
      scheme: bearer
      type: http