openapi: 3.1.0
info:
  title: Basecamp Authorization People API
  description: The Basecamp API is a REST API that provides programmatic access to Basecamp's project management and team communication platform. It enables developers to manage projects, to-do lists, messages, documents, schedules, campfires, uploads, card tables, templates, and team members across Basecamp accounts. The API uses OAuth 2.0 for authentication and returns JSON responses, with all requests scoped to an account ID in the base URL path. Resources include projects, people, to-dos, message boards, documents, card tables, campfires, questionnaires, and webhooks, covering the full breadth of Basecamp's collaboration toolset.
  version: '1.0'
  contact:
    name: Basecamp Developer Support
    url: https://github.com/basecamp/bc3-api
  termsOfService: https://basecamp.com/terms
servers:
- url: https://3.basecampapi.com/{accountId}
  description: Production Server
  variables:
    accountId:
      description: Your Basecamp account ID
      default: '999999999'
security:
- bearerAuth: []
tags:
- name: People
  description: Manage people, profiles, and project access
paths:
  /people.json:
    get:
      operationId: listPeople
      summary: List all people
      description: Returns a paginated list of all people visible to the authenticated user across the account.
      tags:
      - People
      responses:
        '200':
          description: Paginated list of people
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Person'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /projects/{projectId}/people.json:
    get:
      operationId: listProjectPeople
      summary: List people on a project
      description: Returns a paginated list of all people with access to the specified project.
      tags:
      - People
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: List of people on the project
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Person'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /projects/{projectId}/people/users.json:
    put:
      operationId: updateProjectAccess
      summary: Update project access
      description: Grants or revokes access to the project for specific people. Accepts arrays of person IDs to grant or revoke, or new person objects to create and invite.
      tags:
      - People
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectAccessRequest'
      responses:
        '200':
          description: Updated access list
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /circles/people.json:
    get:
      operationId: listPingablePeople
      summary: List pingable people
      description: Returns a paginated list of all people the authenticated user can ping (direct message) within the account.
      tags:
      - People
      responses:
        '200':
          description: List of pingable people
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Person'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /people/{personId}.json:
    get:
      operationId: getPerson
      summary: Get a person
      description: Returns the profile of the person with the given ID.
      tags:
      - People
      parameters:
      - $ref: '#/components/parameters/PersonId'
      responses:
        '200':
          description: Person profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /my/profile.json:
    get:
      operationId: getMyProfile
      summary: Get my profile
      description: Returns the profile of the currently authenticated user.
      tags:
      - People
      responses:
        '200':
          description: Authenticated user profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      operationId: updateMyProfile
      summary: Update my profile
      description: Updates profile fields for the currently authenticated user including name, email address, title, bio, location, and time zone.
      tags:
      - People
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProfileUpdateRequest'
      responses:
        '200':
          description: Updated profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    BadRequest:
      description: Bad request — missing required fields or invalid values
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized — missing or invalid Bearer token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found — the requested resource does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    PersonRef:
      type: object
      description: Minimal reference to a Basecamp person
      properties:
        id:
          type: integer
          description: Person ID
        attachable_sgid:
          type: string
          description: Signed global ID for attaching this person
        name:
          type: string
          description: Full name
        email_address:
          type: string
          format: email
          description: Email address
        personable_type:
          type: string
          description: Type of personable (User, Client, etc.)
        title:
          type: string
          description: Job title
        bio:
          type: string
          description: Short biography
        location:
          type: string
          description: Location string
        created_at:
          type: string
          format: date-time
          description: Account creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
        admin:
          type: boolean
          description: Whether the person is an account administrator
        owner:
          type: boolean
          description: Whether the person is the account owner
        client:
          type: boolean
          description: Whether the person is a client user
        employee:
          type: boolean
          description: Whether the person is an employee
        time_zone:
          type: string
          description: IANA time zone name
        avatar_url:
          type: string
          format: uri
          description: URL to the person's avatar image
        company:
          type: object
          description: Company the person belongs to
          properties:
            id:
              type: integer
              description: Company ID
            name:
              type: string
              description: Company name
    ProfileUpdateRequest:
      type: object
      properties:
        name:
          type: string
          description: Full name
        email_address:
          type: string
          format: email
          description: Email address
        title:
          type: string
          description: Job title
        bio:
          type: string
          description: Short biography
        location:
          type: string
          description: Location string
        time_zone_name:
          type: string
          description: IANA time zone name
    ProjectAccessRequest:
      type: object
      properties:
        grant:
          type: array
          description: Array of person IDs to grant access
          items:
            type: integer
        revoke:
          type: array
          description: Array of person IDs to revoke access
          items:
            type: integer
        create:
          type: array
          description: New people to invite to the project
          items:
            type: object
            required:
            - name
            - email_address
            properties:
              name:
                type: string
                description: Full name of the new person
              email_address:
                type: string
                format: email
                description: Email address of the new person
              title:
                type: string
                description: Job title
              company_name:
                type: string
                description: Company name
    Error:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message
    Person:
      allOf:
      - $ref: '#/components/schemas/PersonRef'
      - type: object
        properties:
          can_ping:
            type: boolean
            description: Whether the authenticated user can direct message this person
          can_manage_projects:
            type: boolean
            description: Whether the person can manage projects
          can_manage_people:
            type: boolean
            description: Whether the person can manage people
          can_access_timesheet:
            type: boolean
            description: Whether the person can access timesheets
          can_access_hill_charts:
            type: boolean
            description: Whether the person can access hill charts
  parameters:
    ProjectId:
      name: projectId
      in: path
      required: true
      description: Unique identifier of the project (bucket)
      schema:
        type: integer
    PersonId:
      name: personId
      in: path
      required: true
      description: Unique identifier of the person
      schema:
        type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'OAuth 2.0 Bearer token obtained via the Basecamp authorization code flow at launchpad.37signals.com. Include as "Authorization: Bearer {token}" in all requests.'
externalDocs:
  description: Basecamp API Documentation
  url: https://github.com/basecamp/bc3-api