1Password Contracts API

openapi: 3.2.0
info:
  title: SaaS Manager Contracts API
  description: 'By accessing or using 1Password Developer Tools, you agree to the API and SDK Terms of Service. ---


    The SaaS Manager public REST API lets you read and manage your applications, people, teams, contracts, devices, workflows and audit log programmatically. Resources are grouped by area (see the navigation). The conventions below apply across the whole API. ## Regions and base URL


    SaaS Manager is hosted in multiple regions. Pick the base URL for your tenant''s region from the **Servers** dropdown — `https://app.trelica.com` (United States) or `https://eu.trelica.com` (Europe). Endpoint URLs throughout this reference use whichever server you select. ## Authentication


    Every request must send an `Authorization` header carrying an OAuth 2.0 access token, prefixed with `Bearer`:


    ```

    Authorization: Bearer

    ```


    Obtain a token using either the **Client Credentials** flow (machine-to-machine) or the **Authorization Code** flow (acting on behalf of a user). The scopes granted to your token determine which endpoints you may call — see Scopes. Access tokens expire. When a token is missing, invalid or expired you receive `401 Unauthorized`; inspect the `WWW-Authenticate` response header for detail, for example:


    ```

    Bearer error="invalid_token", error_description="The token expired at ''12/23/2020 10:27:15''"

    ```


    If you used the Authorization Code flow with the `offline_access` scope, use your refresh token to obtain a new access token. A `403 Forbidden` means the token is valid but lacks the scope required by the endpoint. ## Dates and times


    Dates and date/times are sent and returned in RFC 3339 format (essentially ISO 8601), for example `2020-12-25` (midnight) or `2020-12-25T10:50:00Z`. Field names ending in `Dtm` carry a meaningful time component; field names ending in `Date` are date-only. ## Optional fields and null


    Responses omit fields that have no value — you will see the field absent rather than returned as `null`. When creating or replacing a resource (`PUT`), any field you omit is cleared. With `PATCH`, omitting a field leaves it unchanged, whereas sending it as `null` clears it. ## Pagination


    List endpoints are paginated and return at most 100 results by default. Request a different upper bound with the `limit` query parameter (maximum 1000) — you may receive fewer than requested. Request the next page with the `after` query parameter, passing the opaque cursor token that SaaS Manager supplies. The response''s `next` field (and the `link` response header, `rel="next"`) contains the full URL for the next page:


    ```json

    {

    "next": "https://app.trelica.com/api/people/v1?after=&limit=100",

    "results": [ { /* ... */ } ]

    }

    ```


    Keep requesting pages until no further results are returned. (User data exposed over SCIM uses the SCIM `startIndex`/`count` pagination scheme instead.)


    ## Filtering


    Many list endpoints accept a `filter` query parameter (URL-encoded) based on the SCIM filtering specification. A filter is one or more expressions — an attribute name, an operator, and an optional value — combined with `and`, `or`, `not`, and grouped with parentheses. Attribute names match the JSON returned and may use dot notation for nested attributes

    (e.g. `createdBy.email`). For an attribute that is an **array of objects**, put a sub-expression in

    brackets — the item matches when *any* element satisfies it: `teams[name eq "Developers"]` or

    `teams[id eq "5f8d0a1b2c3d4e5f60718293"]`. Values are strings (double-quoted), integers, dates

    (double-quoted, RFC 3339) or booleans. Some list endpoints also accept a free-text `q` parameter

    that searches the resource''s displayable fields. Soft-deleted entities are excluded by default; include them with a filter that references `deleted` (e.g. `filter=deleted eq true`).'
  contact:
    name: 1Password SaaS Manager Support
    email: saasmanager@1password.com
  version: v1
servers:
- url: https://app.trelica.com
  description: United States
- url: https://eu.trelica.com
  description: Europe
tags:
- name: Contracts
  description: List and manage contracts.
paths:
  /api/contracts/v1:
    get:
      tags:
      - Contracts
      summary: List contracts
      description: 'Returns a paginated list of the contracts in your organization. Use `filter` and

        `q` to narrow the results, and follow the `next` link (also provided in the

        `link` response header) to page through large result sets.


        **Required scope:** `Contracts.Read` (Read-only access to contracts)'
      parameters:
      - name: filter
        in: query
        description: 'A SCIM-style filter expression restricting the items returned. See the Filtering section of the introduction for the operators and syntax; the filterable fields are listed per resource.


          **Filterable fields**


          - **string:** `createdBy.email`, `createdBy.name`, `createdBy.userId`, `documents[description]`, `documents[id]`, `documents[linkUrl]`, `externalId`, `id`, `lastModifiedBy.email`, `lastModifiedBy.name`, `lastModifiedBy.userId`, `lineItems[currency]`, `lineItems[description]`, `lineItems[externalId]`, `lineItems[id]`, `lineItems[notes]`, `notes`, `paymentMethod`, `type`, `vendorName`

          - **number:** `lineItems[amount]`, `lineItems[unitCount]`, `terminationNoticeDays`

          - **date:** `agreementDate`, `createdDtm`, `lastModifiedDtm`, `lineItems[endDate]`, `lineItems[startDate]`, `renewalDate`, `startDate`

          - **boolean:** `deleted`, `isAutomaticRenewal`



          **Filter examples**


          - `vendorName eq "Agilebits Inc"` — Contracts whose vendor is "Agilebits Inc"

          - `vendorName sw "Micros"` — Contracts with vendors starting with "Micros", e.g. "Microsoft"

          - `lineItems[unitCount gt 100]` — Contracts with a line item of more than 100 units

          - `isAutomaticRenewal eq true` — Contracts that automatically renew

          - `agreementDate ge "2021-06-01"` — Contracts with agreement dates on or after 1 Jun 2021'
        schema:
          type: string
      - name: q
        in: query
        description: Free-text search across the resource's displayable fields.
        schema:
          type: string
      - name: since
        in: query
        description: Only return items modified at or after this ISO-8601 timestamp.
        schema:
          type: string
          format: date-time
      - name: until
        in: query
        description: Only return items modified at or before this ISO-8601 timestamp.
        schema:
          type: string
          format: date-time
      - name: after
        in: query
        description: Opaque pagination cursor supplied by SaaS Manager via the `link` response header and the `next` field.
        schema:
          type: string
      - name: limit
        in: query
        description: Maximum number of items to return per page (default 100, maximum 1000).
        schema:
          maximum: 1000
          minimum: 1
          type: integer
          default: 100
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractPage'
              example:
                next: https://app.trelica.com/api/contracts/v1?after=eyJpZCI6IjY2MDk2ODJiZGIzY2Y2ZWM3MmI5NTgzOSJ9&limit=100
                results:
                - id: 6609682bdb3cf6ec72b95839
                  externalId: EXT1235
                  ref: PO-12345-00
                  type: PurchaseOrder
                  vendorName: Github, Inc.
                  agreementDate: '2022-04-01T00:00:00Z'
                  renewalDate: '2023-04-01T00:00:00Z'
                  terminationNoticeDays: 90
                  isAutomaticRenewal: false
                  notes: Annual Github renewal negotiated by Rachele in procurement
                  paymentMethod: Invoice
                  businessOwnerEmail: jane.doe@example.org
                  lineItems:
                  - externalId: '1'
                    description: Github Enterprise annual
                    notes: For source control
                    unitCount: 50
                    amount: 210.0
                    currency: USD
                    baseAmount: 210.0
                    baseCurrency: USD
                    startDate: '2022-04-06T00:00:00Z'
                    endDate: '2023-04-06T00:00:00Z'
                  - externalId: '2'
                    description: Github Advanced Security
                    notes: Secret scanning etc
                    unitCount: 10
                    amount: 250.0
                    currency: USD
                    baseAmount: 250.0
                    baseCurrency: USD
                    startDate: '2022-04-06T00:00:00Z'
                    endDate: '2023-04-06T00:00:00Z'
                  documents: []
                  createdBy:
                    userId: 110e3dd8077945c2a60d33770eb74b97
                    name: Sam Procurement
                    email: sam.procurement@example.org
                  createdDtm: '2024-03-31T13:42:03.608Z'
                  lastModifiedBy:
                    userId: 110e3dd8077945c2a60d33770eb74b97
                    name: Sam Procurement
                    email: sam.procurement@example.org
                  lastModifiedDtm: '2024-03-31T13:42:03.608Z'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                type: about:blank
                title: One or more validation errors occurred.
                status: 400
                detail: The request body failed validation. See errors for the offending fields.
                errors:
                  email:
                  - The email field is required.
                traceId: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
      - oauth2:
        - Contracts.Read
      operationId: getApiContractsV1
      x-operation-id-source: derived
    put:
      tags:
      - Contracts
      summary: Create or update a contract
      description: 'Creates a contract, or updates an existing one matched by its `id` or your own

        `externalId`. Either all line items carry an `externalId` or none do. Set the

        business owner with `businessOwnerEmail`.


        **Required scope:** `Contracts.Write` (Write access to contracts)'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Contract'
            example:
              id: 6609682bdb3cf6ec72b95839
              externalId: EXT1235
              ref: PO-12345-00
              type: PurchaseOrder
              vendorName: Github, Inc.
              agreementDate: '2022-04-01T00:00:00Z'
              renewalDate: '2023-04-01T00:00:00Z'
              terminationNoticeDays: 90
              isAutomaticRenewal: false
              notes: Annual Github renewal negotiated by Rachele in procurement
              paymentMethod: Invoice
              businessOwnerEmail: jane.doe@example.org
              lineItems:
              - externalId: '1'
                description: Github Enterprise annual
                notes: For source control
                unitCount: 50
                amount: 210.0
                currency: USD
                baseAmount: 210.0
                baseCurrency: USD
                startDate: '2022-04-06T00:00:00Z'
                endDate: '2023-04-06T00:00:00Z'
              - externalId: '2'
                description: Github Advanced Security
                notes: Secret scanning etc
                unitCount: 10
                amount: 250.0
                currency: USD
                baseAmount: 250.0
                baseCurrency: USD
                startDate: '2022-04-06T00:00:00Z'
                endDate: '2023-04-06T00:00:00Z'
              documents: []
              createdBy:
                userId: 110e3dd8077945c2a60d33770eb74b97
                name: Sam Procurement
                email: sam.procurement@example.org
              createdDtm: '2024-03-31T13:42:03.608Z'
              lastModifiedBy:
                userId: 110e3dd8077945c2a60d33770eb74b97
                name: Sam Procurement
                email: sam.procurement@example.org
              lastModifiedDtm: '2024-03-31T13:42:03.608Z'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contract'
              example:
                id: 6609682bdb3cf6ec72b95839
                externalId: EXT1235
                ref: PO-12345-00
                type: PurchaseOrder
                vendorName: Github, Inc.
                agreementDate: '2022-04-01T00:00:00Z'
                renewalDate: '2023-04-01T00:00:00Z'
                terminationNoticeDays: 90
                isAutomaticRenewal: false
                notes: Annual Github renewal negotiated by Rachele in procurement
                paymentMethod: Invoice
                businessOwnerEmail: jane.doe@example.org
                lineItems:
                - externalId: '1'
                  description: Github Enterprise annual
                  notes: For source control
                  unitCount: 50
                  amount: 210.0
                  currency: USD
                  baseAmount: 210.0
                  baseCurrency: USD
                  startDate: '2022-04-06T00:00:00Z'
                  endDate: '2023-04-06T00:00:00Z'
                - externalId: '2'
                  description: Github Advanced Security
                  notes: Secret scanning etc
                  unitCount: 10
                  amount: 250.0
                  currency: USD
                  baseAmount: 250.0
                  baseCurrency: USD
                  startDate: '2022-04-06T00:00:00Z'
                  endDate: '2023-04-06T00:00:00Z'
                documents: []
                createdBy:
                  userId: 110e3dd8077945c2a60d33770eb74b97
                  name: Sam Procurement
                  email: sam.procurement@example.org
                createdDtm: '2024-03-31T13:42:03.608Z'
                lastModifiedBy:
                  userId: 110e3dd8077945c2a60d33770eb74b97
                  name: Sam Procurement
                  email: sam.procurement@example.org
                lastModifiedDtm: '2024-03-31T13:42:03.608Z'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                type: about:blank
                title: One or more validation errors occurred.
                status: 400
                detail: The request body failed validation. See errors for the offending fields.
                errors:
                  email:
                  - The email field is required.
                traceId: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
      - oauth2:
        - Contracts.Write
      operationId: putApiContractsV1
      x-operation-id-source: derived
  /api/contracts/v1/{id}:
    get:
      tags:
      - Contracts
      summary: Get a contract
      description: 'Fetches a single contract by its SaaS Manager ID or by your own external ID.


        **Required scope:** `Contracts.Read` (Read-only access to contracts)'
      parameters:
      - name: id
        in: path
        description: The contract's SaaS Manager ID, or the external ID you assigned when importing it.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contract'
              example:
                id: 6609682bdb3cf6ec72b95839
                externalId: EXT1235
                ref: PO-12345-00
                type: PurchaseOrder
                vendorName: Github, Inc.
                agreementDate: '2022-04-01T00:00:00Z'
                renewalDate: '2023-04-01T00:00:00Z'
                terminationNoticeDays: 90
                isAutomaticRenewal: false
                notes: Annual Github renewal negotiated by Rachele in procurement
                paymentMethod: Invoice
                businessOwnerEmail: jane.doe@example.org
                lineItems:
                - externalId: '1'
                  description: Github Enterprise annual
                  notes: For source control
                  unitCount: 50
                  amount: 210.0
                  currency: USD
                  baseAmount: 210.0
                  baseCurrency: USD
                  startDate: '2022-04-06T00:00:00Z'
                  endDate: '2023-04-06T00:00:00Z'
                - externalId: '2'
                  description: Github Advanced Security
                  notes: Secret scanning etc
                  unitCount: 10
                  amount: 250.0
                  currency: USD
                  baseAmount: 250.0
                  baseCurrency: USD
                  startDate: '2022-04-06T00:00:00Z'
                  endDate: '2023-04-06T00:00:00Z'
                documents: []
                createdBy:
                  userId: 110e3dd8077945c2a60d33770eb74b97
                  name: Sam Procurement
                  email: sam.procurement@example.org
                createdDtm: '2024-03-31T13:42:03.608Z'
                lastModifiedBy:
                  userId: 110e3dd8077945c2a60d33770eb74b97
                  name: Sam Procurement
                  email: sam.procurement@example.org
                lastModifiedDtm: '2024-03-31T13:42:03.608Z'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                type: about:blank
                title: Not found.
                status: 404
                detail: The requested resource does not exist or you do not have access to it.
                traceId: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
      - oauth2:
        - Contracts.Read
      operationId: getApiContractsV1ById
      x-operation-id-source: derived
    delete:
      tags:
      - Contracts
      summary: Delete a contract
      description: 'Deletes a contract by its SaaS Manager ID or by your own external ID.


        **Required scope:** `Contracts.Write` (Write access to contracts)'
      parameters:
      - name: id
        in: path
        description: The contract's SaaS Manager ID, or the external ID you assigned when importing it.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                type: about:blank
                title: Not found.
                status: 404
                detail: The requested resource does not exist or you do not have access to it.
                traceId: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
      - oauth2:
        - Contracts.Write
      operationId: deleteApiContractsV1ById
      x-operation-id-source: derived
components:
  schemas:
    ContractLineItem:
      type: object
      properties:
        externalId:
          type:
          - string
          - 'null'
          description: Your own external ID for the line item. Either all line items have one, or none do.
        description:
          type:
          - string
          - 'null'
          description: A description of the line item
        notes:
          type:
          - string
          - 'null'
          description: Notes about the line item
        unitCount:
          type:
          - integer
          - 'null'
          description: The number of units
          format: int32
        amount:
          type:
          - number
          - 'null'
          description: The amount, in the currency given by currency
          format: double
        currency:
          type:
          - string
          - 'null'
          description: The ISO currency code for amount. Defaults to your base currency.
        baseAmount:
          type:
          - number
          - 'null'
          description: The amount converted to your base currency
          format: double
          readOnly: true
        baseCurrency:
          type:
          - string
          - 'null'
          description: Your base ISO currency code
          readOnly: true
        startDate:
          type:
          - string
          - 'null'
          description: (ISO format) The line item's start date
          format: date-time
        endDate:
          type:
          - string
          - 'null'
          description: (ISO format) The line item's end date
          format: date-time
      additionalProperties: false
      description: A line item on a contract
    Contract:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: The contract's SaaS Manager ID. Supply to update an existing contract.
        externalId:
          type:
          - string
          - 'null'
          description: Your own external ID for the contract. Supply to match an existing contract on update.
        ref:
          type:
          - string
          - 'null'
          description: A reference for the contract, e.g. a PO number
        type:
          allOf:
          - $ref: '#/components/schemas/ContractType'
          description: The contract type
        vendorName:
          type:
          - string
          - 'null'
          description: The vendor name
        startDate:
          type:
          - string
          - 'null'
          description: (ISO format) The contract's start date
          format: date-time
        agreementDate:
          type:
          - string
          - 'null'
          description: (ISO format) The agreement date. Defaults to now on creation.
          format: date-time
        renewalDate:
          type:
          - string
          - 'null'
          description: (ISO format) The renewal date
          format: date-time
        isRolling:
          type:
          - boolean
          - 'null'
          description: Whether the contract is a rolling contract
        terminationNoticeDays:
          type:
          - integer
          - 'null'
          description: The number of days' notice required to terminate the contract
          format: int32
        isAutomaticRenewal:
          type:
          - boolean
          - 'null'
          description: Whether the contract renews automatically
        notes:
          type:
          - string
          - 'null'
          description: Notes about the contract
        paymentMethod:
          allOf:
          - $ref: '#/components/schemas/AppLicensePaymentMethod'
          description: The payment method
        businessOwnerEmail:
          type:
          - string
          - 'null'
          description: The email address of the contract's business owner
        lineItems:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ContractLineItem'
          description: The contract's line items
        documents:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ContractDocument'
          description: Documents linked to the contract
        createdBy:
          allOf:
          - $ref: '#/components/schemas/UserInfo'
          description: The user that created the contract record
          readOnly: true
        createdDtm:
          type:
          - string
          - 'null'
          description: The timestamp for when the contract record was created
          format: date-time
          readOnly: true
        lastModifiedBy:
          allOf:
          - $ref: '#/components/schemas/UserInfo'
          description: The user that last modified the contract record
          readOnly: true
        lastModifiedDtm:
          type:
          - string
          - 'null'
          description: The timestamp for when the contract record was last modified
          format: date-time
          readOnly: true
      additionalProperties: false
      description: A contract
    UserInfo:
      type: object
      properties:
        userId:
          type:
          - string
          - 'null'
        name:
          type:
          - string
          - 'null'
        email:
          type:
          - string
          - 'null'
      additionalProperties: false
    ContractPage:
      type: object
      properties:
        next:
          type: string
          description: The URL of the next page of results. Absent when there are no more results.
        results:
          type: array
          items:
            $ref: '#/components/schemas/Contract'
          description: The page of results.
      additionalProperties: false
    Error:
      type: object
      properties:
        type:
          type: string
          description: A URI reference identifying the problem type.
        title:
          type: string
          description: A short, human-readable summary of the problem.
        status:
          type: integer
          description: The HTTP status code.
          format: int32
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Validation errors keyed by field name. Present on 400 responses.
        traceId:
          type: string
          description: A trace identifier for correlating the error with SaaS Manager support.
      additionalProperties: false
      description: An error response (RFC 7807 problem details).
    ContractDocument:
      type: object
      properties:
        linkUrl:
          type:
          - string
          - 'null'
          description: A URL linking to the document
        description:
          type:
          - string
          - 'null'
          description: A description of the document
      additionalProperties: false
      description: A document linked to a contract
    AppLicensePaymentMethod:
      enum:
      - CreditCard
      - Invoice
      type: string
    ContractType:
      enum:
      - OrderForm
      - MSA
      - GenericContract
      - PurchaseOrder
      - Subscription
      type: string
  securitySchemes:
    oauth2:
      type: oauth2
      description: 'OAuth 2.0. Obtain an access token via the Client Credentials or Authorization Code flow, then send it as `Authorization: Bearer <token>`.'
      flows:
        clientCredentials:
          tokenUrl: https://app.trelica.com/connect/token
          scopes:
            Apps.Read: Read-only access to applications
            Apps.Users.Read: Read-only access to application accounts
            Apps.Write: Write access to applications
            Assets.Read: Read-only access to devices
            Assets.Write: Write access to devices
            AuditLog.Read: Read-only access to the audit log
            Contracts.Read: Read-only access to contracts
            Contracts.Write: Write access to contracts
            People.Read: Read-only access to people and teams
            People.Write: Write access to people and teams
            Users.Read: Read-only access to users with access to SaaS Manager
            Users.Write: Write access to users with access to SaaS Manager
            Workflows.Read: Read-only access to workflow definitions
            Workflows.Runs.Read: Read-only access to workflow runs
            Workflows.Runs.Execute: Execute workflow run actions
            Workflows.Runs.ReadSecrets: Read workflow run secrets
            offline_access: Issue a refresh token alongside the access token (Authorization Code flow)
        authorizationCode:
          authorizationUrl: https://app.trelica.com/connect/authorize
          tokenUrl: https://app.trelica.com/connect/token
          scopes:
            Apps.Read: Read-only access to applications
            Apps.Users.Read: Read-only access to application accounts
            Apps.Write: Write access to applications
            Assets.Read: Read-only access to devices
            Assets.Write: Write access to devices
            AuditLog.Read: Read-only access to the audit log
            Contracts.Read: Read-only access to contracts
            Contracts.Write: Write access to contracts
            People.Read: Read-only access to people and teams
            People.Write: Write access to people and teams
            Users.Read: Read-only access to users with access to SaaS Manager
            Users.Write: Write access to users with access to SaaS Manager
            Workflows.Read: Read-only access to workflow definitions
            Workflows.Runs.Read: Read-only access to workflow runs
            Workflows.Runs.Execute: Execute workflow run actions
            Workflows.Runs.ReadSecrets: Read workflow run secrets
            offline_access: Issue a refresh token alongside the access token (Authorization Code flow)
    bearerAuth:
      type: http
      description: A bearer access token obtained via OAuth 2.0.
      scheme: bearer
      bearerFormat: JWT
    clientBasicAuth:
      type: http
      description: 'HTTP Basic authentication: the client ID and client secret, joined with a colon and Base64-encoded (RFC 7617).'
      scheme: basic
x-provenance:
  method: harvested
  publisher: 1Password
  source: https://www.1password.dev/openapi/saas_manager_api.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)