Buildertrend Jobs API

List and read the jobs the linked user can see, create jobs from the linked user's templates, and read the people on those jobs.

GitHub OpenAPI

Operations 5

GET /v1/jobs List jobs #
POST /v1/jobs Create a job from a template #
GET /v1/jobs/templates List job templates #
GET /v1/jobs/{jobId} Get one job #
GET /v1/jobs/{jobId}/users List users on a job #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/buildertrend:buildertrend-jobs-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

buildertrend-jobs-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Buildertrend Jobs API
  version: '1'
  description: 'Operations tagged Jobs across 2 of this provider''s published API definitions: buildertrend-open-api-reference.yml, buildertrend-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://developer.buildertrend.com/api
security:
- clientCredentials: []
tags:
- name: Jobs
  description: List and read the jobs the linked user can see, create jobs from the linked user's templates, and read the people on those jobs.
paths:
  /v1/jobs:
    get:
      tags:
      - Jobs
      operationId: listJobs
      summary: List jobs
      description: 'Lists the jobs the linked user can see, ordered by name: open, presale, warranty and closed

        jobs, never deleted ones. Templates are listed separately by `GET /v1/jobs/templates`.

        A job''s `id` is the `jobId` every job-scoped route and filter takes.'
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/cursor'
      responses:
        '200':
          description: A page of jobs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobCollection'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Buildertrend denied the linked user access to jobs.
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      tags:
      - Jobs
      operationId: createJob
      summary: Create a job from a template
      description: 'Creates a job from one of the templates `GET /v1/jobs/templates` lists. The job gets the

        template''s work days, project managers, sub permissions and the template items Buildertrend

        pre-selects for a new job, such as its schedule, document folders and tasks. Its schedule

        starts on `startDate`. Buildertrend copies the template''s items in the background, so they

        can appear a few moments after the `201`.


        **What is copied is decided by the template, not by this request.** It is exactly what

        Buildertrend''s own "create job from template" screen pre-selects for that template, and the

        request has no field to change it. So a new job usually arrives with the template''s tasks

        already on it. To start a job empty, use a template with nothing pre-selected.


        **There is no endpoint to delete a job.** A job created by mistake has to be deleted in

        Buildertrend.


        The linked user needs permission to add jobs in Buildertrend, otherwise the call is `403`.

        A `templateId` the linked user can''t see is a `400` on `templateId`, the same as one that

        doesn''t exist.


        Don''t retry a `5xx` blindly: the job may have been created anyway. Check in Buildertrend

        before you send the request again.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobCreateRequest'
      responses:
        '201':
          description: The job was created. `Location` is its URL, for `GET /v1/jobs/{jobId}`.
          headers:
            Location:
              description: The new job's path, e.g. `/api/v1/jobs/5b2a7c1e-3f4d-4e8a-9c6b-1d2e3f4a5b6c`.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobCreated'
        '400':
          description: A field is missing or invalid, the template isn't available to the linked user, or `jobType` isn't a Buildertrend job type. `errors` names each field; for an unknown `jobType` the message lists the valid names.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblem'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: The linked user doesn't have permission to add jobs.
        '429':
          $ref: '#/components/responses/TooManyRequests'
    servers:
    - url: https://developer.buildertrend.com/api
  /v1/jobs/templates:
    get:
      tags:
      - Jobs
      operationId: listJobTemplates
      summary: List job templates
      description: 'Lists the templates the linked user can create jobs from, ordered by name. Only standalone

        templates are listed: a job that the builder also uses as a template is not included.'
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/cursor'
      responses:
        '200':
          description: A page of templates.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobTemplateCollection'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Buildertrend denied the linked user access to job templates.
        '429':
          $ref: '#/components/responses/TooManyRequests'
    servers:
    - url: https://developer.buildertrend.com/api
  /v1/jobs/{jobId}:
    get:
      tags:
      - Jobs
      operationId: getJob
      summary: Get one job
      description: 'Returns one job with its address, clients, contract type, contract price and project managers.

        Every field is always present: a value Buildertrend doesn''t have is `null`, and a list with

        nothing in it is `[]`.


        A job the linked user can''t see is `404`, the same as one that doesn''t exist or belongs to

        another builder. A `404` can also mean the user lacks view permission on Jobs in Buildertrend.

        A `jobId` that isn''t a GUID is `404` too.


        `contractPrice` is a decimal string, in the account''s own currency exactly as entered in

        Buildertrend. It''s `null` when the linked user can''t view job prices.


        For now, edits to the job''s status, project managers, job groups or custom fields do not change

        `updatedAt`.'
      parameters:
      - name: jobId
        in: path
        required: true
        description: The ID of the job to read, from `GET /v1/jobs`.
        schema:
          type: string
          format: uuid
        example: 5b2a7c1e-3f4d-4e8a-9c6b-1d2e3f4a5b6c
      responses:
        '200':
          description: The job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobDetails'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: The job doesn't exist, isn't the linked user's, or the user can't see it. Also a `jobId` that isn't a GUID.
        '429':
          $ref: '#/components/responses/TooManyRequests'
    servers:
    - url: https://developer.buildertrend.com/api
  /v1/jobs/{jobId}/users:
    get:
      tags:
      - Jobs
      operationId: listJobUsers
      summary: List users on a job
      description: 'Lists the users available on one job, ordered by name: active internal users and subs with

        access to the job, plus the job''s active contacts. It is the same list Buildertrend''s task

        assignee picker offers for that job.


        `jobId` is the job''s ID (a GUID) from `GET /v1/jobs`. A job the linked user

        can''t see is `403`, the same as one that doesn''t exist or belongs to another builder. A `403`

        can also mean the user lacks view permission on Jobs in Buildertrend. A `jobId` that isn''t a

        GUID is `404`.'
      parameters:
      - name: jobId
        in: path
        required: true
        description: The ID of the job to read.
        schema:
          type: string
          format: uuid
        example: 5b2a7c1e-3f4d-4e8a-9c6b-1d2e3f4a5b6c
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/cursor'
      responses:
        '200':
          description: A page of users.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobUserCollection'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: The `jobId` is not a GUID.
        '429':
          $ref: '#/components/responses/TooManyRequests'
    servers:
    - url: https://developer.buildertrend.com/api
components:
  schemas:
    JobClient:
      type: object
      required:
      - id
      - firstName
      - lastName
      - displayName
      properties:
        id:
          type: string
          format: uuid
          description: The client's user ID. `GET /api/v1/jobs/{jobId}/users` lists the same ID, except for the placeholder client Buildertrend creates for a job that has no named client.
          example: 5a4b3c2d-1e0f-4968-8776-0f1e2d3c4b5a
        firstName:
          type:
          - string
          - 'null'
          example: Pat
        lastName:
          type:
          - string
          - 'null'
          example: Smith
        displayName:
          type: string
          description: The client's full name as Buildertrend shows it.
          example: Pat Smith
    Job:
      type: object
      required:
      - id
      - name
      - status
      properties:
        id:
          type: string
          format: uuid
          description: The job's ID. Send it as `jobId` to the job-scoped routes and filters.
          example: 7d1e9c2a-5b3f-4e6d-8a9b-0c1d2e3f4a5b
        name:
          type: string
          example: Smith Residence
        status:
          type: string
          enum:
          - Open
          - Presale
          - Warranty
          - Closed
          - Unknown
          description: '`Unknown` if Buildertrend returns a status this API doesn''t recognise yet. Deleted jobs are never listed.'
          example: Open
    JobProjectManager:
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: string
          format: uuid
          description: The user's ID, as `GET /v1/jobs/{jobId}/users` lists it.
          example: 0f1e2d3c-4b5a-4968-8776-5a4b3c2d1e0f
        name:
          type: string
          example: Dana Ruiz
    JobAddress:
      type: object
      description: 'Always present. Each part is `null` when it''s blank in Buildertrend. There is no country: Buildertrend stores none for a job.'
      required:
      - street
      - suburb
      - city
      - state
      - zip
      properties:
        street:
          type:
          - string
          - 'null'
          example: 123 Main St
        suburb:
          type:
          - string
          - 'null'
          example: null
        city:
          type:
          - string
          - 'null'
          example: Omaha
        state:
          type:
          - string
          - 'null'
          example: NE
        zip:
          type:
          - string
          - 'null'
          example: '68102'
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          example: api_key_not_linked
        message:
          type: string
    ValidationProblem:
      type: object
      properties:
        message:
          type: string
          example: One or more validation errors occurred.
        errors:
          type: array
          items:
            type: object
            properties:
              path:
                type: string
                description: The request field the error concerns.
                example: JobType
              message:
                type: string
                example: '''Spaceship'' is not a job type. Valid job types: Basement, Custom, Kitchen.'
    JobCreateRequest:
      type: object
      required:
      - templateId
      - name
      - startDate
      - jobType
      properties:
        templateId:
          type: string
          format: uuid
          description: The `id` of a template from `GET /v1/jobs/templates`.
          example: 3c9d2e1f-4a5b-4c6d-8e7f-9a0b1c2d3e4f
        name:
          type: string
          maxLength: 50
          description: The new job's name.
          example: Smith Kitchen
        startDate:
          type: string
          format: date
          description: The projected start date, in the builder's time zone. The template's schedule is moved to start on it.
          example: '2026-11-02'
        jobType:
          type: string
          description: The job type as Buildertrend names it, e.g. `Kitchen`, `Custom` or `Basement`. Matched ignoring case. An unknown name is a `400` whose message lists the valid ones.
          example: Kitchen
    JobDetails:
      type: object
      required:
      - id
      - name
      - status
      - jobType
      - templateId
      - contractType
      - address
      - clients
      - contractPrice
      - projectManagers
      - createdAt
      - updatedAt
      properties:
        id:
          type: string
          format: uuid
          description: The job's ID. Send it as `jobId` to the job-scoped routes and filters.
          example: 5b2a7c1e-3f4d-4e8a-9c6b-1d2e3f4a5b6c
        name:
          type: string
          example: Smith Kitchen Remodel
        status:
          type: string
          enum:
          - Open
          - Presale
          - Warranty
          - Closed
          - Unknown
          description: '`Unknown` if Buildertrend returns a status this API doesn''t recognise yet.'
          example: Open
        jobType:
          type:
          - string
          - 'null'
          description: The job type as Buildertrend names it.
          example: Kitchen
        templateId:
          type:
          - string
          - 'null'
          format: uuid
          description: The `id` of the template the job was created from, if any.
          example: 3c9d2e1f-4a5b-4c6d-8e7f-9a0b1c2d3e4f
        contractType:
          type:
          - string
          - 'null'
          enum:
          - FixedPrice
          - OpenBook
          - null
          description: How the job is priced. `null` if Buildertrend returns a contract type this API doesn't recognise yet.
          example: FixedPrice
        address:
          $ref: '#/components/schemas/JobAddress'
        clients:
          type: array
          description: The job's clients. Empty if it has none.
          items:
            $ref: '#/components/schemas/JobClient'
        contractPrice:
          type:
          - string
          - 'null'
          pattern: ^-?(0|[1-9]\d{0,13})(\.\d{1,2})?$
          description: A decimal string with two decimal places, in the account's own currency exactly as entered in Buildertrend. There's no currency code. `null` when the linked user can't view job prices. Parse it as a decimal, not a float.
          example: '84500.00'
        projectManagers:
          type: array
          description: Empty if the job has none.
          items:
            $ref: '#/components/schemas/JobProjectManager'
        createdAt:
          type: string
          format: date-time
          description: UTC.
          example: '2026-10-26T15:04:11Z'
        updatedAt:
          type: string
          format: date-time
          description: UTC. For now, it doesn't change for edits to the job's status, project managers, job groups or custom fields.
          example: '2026-10-26T15:04:11Z'
    JobTemplate:
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: string
          format: uuid
          description: Send this as `templateId` to create a job from the template.
          example: 3c9d2e1f-4a5b-4c6d-8e7f-9a0b1c2d3e4f
        name:
          type: string
          example: Kitchen Remodel
    JobUserCollection:
      type: object
      required:
      - data
      - pagination
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/JobUser'
        pagination:
          $ref: '#/components/schemas/Pagination'
    JobUser:
      type: object
      required:
      - id
      - name
      - userType
      properties:
        id:
          type: string
          format: uuid
          description: The ID of this user's link to the builder. A person linked to several builders has a different value on each.
          example: 0f1e2d3c-4b5a-4968-8776-5a4b3c2d1e0f
        name:
          type: string
          example: Alice Builder
        userType:
          type: string
          enum:
          - InternalUser
          - Sub
          - Contact
          - Unknown
          description: '`Unknown` if Buildertrend returns a kind of user this API does not recognise yet.'
          example: InternalUser
    Pagination:
      type: object
      required:
      - limit
      - hasMore
      - nextCursor
      properties:
        limit:
          type: integer
          example: 50
        hasMore:
          type: boolean
          example: false
        nextCursor:
          type:
          - string
          - 'null'
          description: Pass back as `cursor` while `hasMore` is true.
    JobCollection:
      type: object
      required:
      - data
      - pagination
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Job'
        pagination:
          $ref: '#/components/schemas/Pagination'
    JobTemplateCollection:
      type: object
      required:
      - data
      - pagination
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/JobTemplate'
        pagination:
          $ref: '#/components/schemas/Pagination'
    JobCreated:
      type: object
      required:
      - id
      properties:
        id:
          type: string
          format: uuid
          description: The new job's ID, the `jobId` other job endpoints take.
          example: 5b2a7c1e-3f4d-4e8a-9c6b-1d2e3f4a5b6c
  responses:
    Unauthorized:
      description: '`missing_token` (no Bearer header), `invalid_token` (expired or wrong token), or `api_key_not_linked` (the token is fine, but the app has no linked Buildertrend account; see the linking step above).'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: A parameter is invalid, e.g. `limit` out of range or a malformed cursor.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationProblem'
    Forbidden:
      description: The linked user can't see this job or record. You can't tell "doesn't exist" from "not yours", by design.
    TooManyRequests:
      description: 'Rate limited: at most 60 requests per minute per app, counted across every endpoint. Back off and retry; don''t retry in a tight loop.'
  parameters:
    cursor:
      name: cursor
      in: query
      required: false
      description: '`pagination.nextCursor` from the previous page. Opaque: don''t parse, build or reuse one, and send the same filters with it. A malformed cursor is a `400`.'
      schema:
        type: string
    limit:
      name: limit
      in: query
      required: false
      description: Page size, 1 to 200. A value outside that range is a `400`, not a silent clamp.
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 50
  securitySchemes:
    clientCredentials:
      type: oauth2
      description: 'Exchange your app''s consumer key and secret at `POST /token`, then send the returned token as `Authorization: Bearer <token>`.'
      flows:
        clientCredentials:
          tokenUrl: /api/token
          scopes: {}
    consumerCredentials:
      type: http
      scheme: basic
      description: Consumer key as the username, consumer secret as the password.
x-refined-from:
- buildertrend-open-api-reference.yml
- buildertrend-openapi.yml