> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paraform.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List an agency member's approved roles

> Use for roles one agency member already works on. New roles: searchAgencyRoles. One role's brief: getAgencyRole. Not agency-wide union. Several narrowing flags match ANY. Page can be short or empty while nextCursor set; continue until null. Approval does not mean given candidate can be submitted.

Required scopes: `agency_roles:read`.



## OpenAPI

````yaml /api/openapi.json get /agency/roles
openapi: 3.0.0
info:
  title: Paraform API
  version: v1
servers:
  - url: https://external-api.paraform.com/api/external/v1
security: []
paths:
  /agency/roles:
    get:
      summary: List an agency member's approved roles
      description: >-
        Use for roles one agency member already works on. New roles:
        searchAgencyRoles. One role's brief: getAgencyRole. Not agency-wide
        union. Several narrowing flags match ANY. Page can be short or empty
        while nextCursor set; continue until null. Approval does not mean given
        candidate can be submitted.


        Required scopes: `agency_roles:read`.
      operationId: listAgencyRoles
      parameters:
        - schema:
            type: string
            maxLength: 254
            format: email
            description: >-
              Email of currently approved member of your agency, e.g.
              jane@agency.com. Results use that member's permissions; does not
              authenticate key holder. Unknown, other-agency, or unapproved
              member answers 403.
          required: true
          description: >-
            Email of currently approved member of your agency, e.g.
            jane@agency.com. Results use that member's permissions; does not
            authenticate key holder. Unknown, other-agency, or unapproved member
            answers 403.
          name: recruiterEmail
          in: query
        - schema:
            type: string
            minLength: 1
            maxLength: 200
            description: >-
              Matched against role titles and company names in member's approved
              roles, e.g. backend engineer. 1-200 characters.
          required: false
          description: >-
            Matched against role titles and company names in member's approved
            roles, e.g. backend engineer. 1-200 characters.
          name: query
          in: query
        - schema:
            anyOf:
              - type: string
                enum:
                  - 'true'
                  - 'false'
              - type: boolean
            description: >-
              Only roles where member holds approved primary slot. Default
              false.
          required: false
          description: Only roles where member holds approved primary slot. Default false.
          name: primaryOnly
          in: query
        - schema:
            anyOf:
              - type: string
                enum:
                  - 'true'
                  - 'false'
              - type: boolean
            description: >-
              Only primary slots with trial still in progress. Default false.
              Trial ends when window closes or submission goal met.
          required: false
          description: >-
            Only primary slots with trial still in progress. Default false.
            Trial ends when window closes or submission goal met.
          name: activeTrialOnly
          in: query
        - schema:
            anyOf:
              - type: string
                enum:
                  - 'true'
                  - 'false'
              - type: boolean
            description: >-
              Only roles where member has active single submission (submitted,
              reviewed, interviewing, offer). Default false. Includes roles
              whose approval since withdrawn.
          required: false
          description: >-
            Only roles where member has active single submission (submitted,
            reviewed, interviewing, offer). Default false. Includes roles whose
            approval since withdrawn.
          name: singleSubmissionsOnly
          in: query
        - schema:
            anyOf:
              - type: string
                enum:
                  - 'true'
                  - 'false'
              - type: boolean
            description: >-
              Only roles where member has active submission (submitted,
              reviewed, interviewing, offer) from ParaAI match. Default false.
              Includes roles whose approval since withdrawn.
          required: false
          description: >-
            Only roles where member has active submission (submitted, reviewed,
            interviewing, offer) from ParaAI match. Default false. Includes
            roles whose approval since withdrawn.
          name: paraAiOnly
          in: query
        - schema:
            type: string
            nullable: true
            enum:
              - ACTIVE
              - PAUSED
              - CLOSED
            default: ACTIVE
            description: >-
              ACTIVE (default), PAUSED, or CLOSED (includes hired, churned).
              Unrecognized value falls back to ACTIVE. Pending, rejected,
              disqualified roles never returned.
          required: false
          description: >-
            ACTIVE (default), PAUSED, or CLOSED (includes hired, churned).
            Unrecognized value falls back to ACTIVE. Pending, rejected,
            disqualified roles never returned.
          name: status
          in: query
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
            description: Roles per page, 1-100, default 50. Above 100 rejected with 400.
          required: false
          description: Roles per page, 1-100, default 50. Above 100 rejected with 400.
          name: limit
          in: query
        - schema:
            type: string
            minLength: 1
            maxLength: 2048
            description: >-
              Previous page's nextCursor. Only with same recruiterEmail, query,
              status, filters; changed filter answers 400, so start new first
              page.
          required: false
          description: >-
            Previous page's nextCursor. Only with same recruiterEmail, query,
            status, filters; changed filter answers 400, so start new first
            page.
          name: cursor
          in: query
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  roles:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        title:
                          type: string
                        company:
                          type: object
                          properties:
                            name:
                              type: string
                          required:
                            - name
                          additionalProperties: false
                        status:
                          type: string
                          enum:
                            - ACTIVE
                            - PAUSED
                            - CLOSED
                        locations:
                          type: array
                          items:
                            type: string
                        workplaceType:
                          type: string
                          nullable: true
                          enum:
                            - REMOTE
                            - HYBRID
                            - ON_SITE
                        baseSalary:
                          type: object
                          nullable: true
                          properties:
                            currency:
                              type: string
                              nullable: true
                            min:
                              type: integer
                              nullable: true
                            max:
                              type: integer
                              nullable: true
                          required:
                            - currency
                            - min
                            - max
                          additionalProperties: false
                          description: >-
                            Annual candidate base salary, whole currency units,
                            no conversion. Null currency means unknown, not USD.
                        updatedAt:
                          type: string
                          format: date-time
                      required:
                        - id
                        - title
                        - company
                        - status
                        - locations
                        - workplaceType
                        - baseSalary
                        - updatedAt
                      additionalProperties: false
                  nextCursor:
                    type: string
                    nullable: true
                required:
                  - roles
                  - nextCursor
                additionalProperties: false
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.