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

# Create Maintenance Agreement

```jsonc Body raw (json) wrap expandable theme={null}
{
  "customer_id",// nullable | required, if is_template is false or not set | integer | existing customer id | prohibited when is_template is true
  "title",// required | string | max:255
  "status_id",// required | integer | existing custom status id | description: object type maintenance_agreement
  "status_workflow_id",// nullable | integer | existing status workflow id | description: object type maintenance_agreement
  "customer_contact_id",// nullable | integer | existing customer contact id | prohibited when is_template is true
  "parent_invoice_id",// nullable | integer | existing invoice id | description: not a template, and the agreement customer when a customer is set
  "timezone",// nullable | string | description: PHP timezone identifier
  "start_time",// nullable | integer | description: timestamp. A date string is also accepted.
  "end_time",// nullable | integer | description: timestamp, same as or after start_time. A date string is also accepted.
  "job_location",// nullable | string | max:255
  "agreement_notes",// nullable | string
  "job_notes",// nullable | string
  "is_template",// nullable | boolean
  "asset_ids",// nullable | array | description: array of existing asset ids
  "settings",// nullable | array | description: stored as sent. No child-key rules.
  "tags",// nullable | array | description: tag ids, or objects {"id": tag id}. Type must be maintenance_agreement.
  "assignments": [// nullable | array | description: teams only. Each team is expanded to one assignment per member.
    {
      "team_id",// required | integer | existing team id
    }
  ],
  "location_id",// nullable | integer | existing location id | prohibited when is_template is true | description: a location of the agreement customer
  "parent_job_id",// nullable | integer | existing job id | description: not a template, and the agreement customer when a customer is set
  "services_routines": [// required, if billing_routines is not set | array | max:5 | description: full list. An active agreement requires at least one. A scheduled routine cannot carry on_demand_generation_method. An on-demand routine cannot carry schedule_generation_method.
    {
      "id",// nullable | integer | existing service routine id | description: omit to create
      "title",// required | string | max:255
      "rrule",// required, if type is scheduled | nullable | string | description: valid rrule
      "type",// required | string | acceptable_values: scheduled,on-demand
      "asset_ids",// nullable | array | description: array of existing asset ids
      "schedule_generation_method": {// required, if type is scheduled | prohibited, if type is on-demand | array
        "creation_method",// required, if schedule_generation_method is set | nullable | string | acceptable_values: manual,automatic
        "automatic_creation_method",// required, if schedule_generation_method is set | string | acceptable_values: automatic,find-availability,fixed
        "generation_window_in_month",// required, if schedule_generation_method is set | integer | acceptable_values: 1,2,3,6,12,13,18,24
        "set_job_template",// nullable | boolean | description: must be true when automatic_creation_method is fixed
        "job_template_id",// required, if set_job_template is true | nullable | integer | existing job template id
        "fixed_method_rrule",// required, if automatic_creation_method is fixed | nullable | string | description: valid rrule with no start or end
        "scheduled_details",// required, if automatic_creation_method is find-availability | nullable | array | description: stored as sent. No child-key rules.
      },
      "on_demand_generation_method": {// required, if type is on-demand | prohibited, if type is scheduled | array
        "generation_window_in_month",// required, if on_demand_generation_method is set | integer | min:1
        "amount_of_services",// required, if on_demand_generation_method is set | integer | min:1
        "unused_services_policy",// required, if on_demand_generation_method is set | string | acceptable_values: expire,rollover
        "set_job_template",// nullable | boolean
        "job_template_id",// required, if set_job_template is true | nullable | integer | existing job template id
      },
      "initial_occurrence_job_id",// nullable | integer | existing job id | description: create only. The job already booked for the first occurrence.
    }
  ],
  "services_routine_overlaps": [// optional | array | description: dropped unless both indexed routines are scheduled and creation_method is automatic. One overlap per pair.
    {
      "id",// nullable | integer | existing overlap id
      "first_routine_index",// required | integer | min:0 | description: index in services_routines
      "second_routine_index",// required | integer | min:0 | description: a different services_routines index. The pair may appear only once.
      "generation_method": {// required | array
        "creation_method",// nullable | string | acceptable_values: manual,automatic
        "automatic_creation_method",// required | string | acceptable_values: automatic,find-availability,fixed
        "generation_window_in_month",// required | integer | acceptable_values: 1,2,3,6,12,13,18,24
        "set_job_template",// nullable | boolean | description: must be true when automatic_creation_method is fixed
        "job_template_id",// required, if set_job_template is true | nullable | integer | existing job template id
        "fixed_method_rrule",// required, if automatic_creation_method is fixed | nullable | string | description: valid rrule with no start or end
        "scheduled_details",// required, if automatic_creation_method is find-availability | nullable | array | description: stored as sent. No child-key rules.
      }
    }
  ],
  "communication": [// optional | array | description: full list. Triggers omitted from the payload are deleted.
    {
      "id",// nullable | integer | existing communication trigger id
      "send_type",// required | string | acceptable_values: email,sms
      "target_routine_mode",// required | string | acceptable_values: all,multiple,single
      "type",// nullable | string | acceptable_values: reminder,renewal
      "routine_indexes",// required, if target_routine_mode is single or multiple | nullable | array | description: services_routines indexes. Exactly one when target_routine_mode is single. Not checked when target_routine_mode is all.
      "notify_before_date_in_days",// required | integer | min:0
      "scheduled_statuses",// nullable | array | description: acceptable values draft,unscheduled,scheduled,completed,failed. Stored as a comma-separated string.
      "user_to_send",// nullable | array | description: array of existing user ids. Stored as a comma-separated string.
      "email_subject",// required, if send_type is email | nullable | string | max:255
      "body",// required | string
      "send_to_users",// required | boolean
      "send_to_customer",// required | boolean
    }
  ],
  "billing_routines": [// optional | array | max:1 | description: an active agreement requires exactly one
    {
      "id",// nullable | integer | existing billing routine id
      "title",// required | string | max:255
      "creation_method",// required | string | acceptable_values: manual,recurring-billing
      "rrule",// required, if creation_method is manual | nullable | string | description: valid rrule
      "recurring_billing_id",// required, if creation_method is recurring-billing | prohibited, if creation_method is manual | nullable | integer | existing recurring billing id
      "price_per_bill",// required | numeric | min:0
      "generation_window_in_month",// required | integer | min:1
      "initial_occurrence_estimate_id",// nullable | integer | existing estimate id | description: mutually exclusive with initial_occurrence_invoice_id
      "initial_occurrence_invoice_id",// nullable | integer | existing invoice id | description: create only. Mutually exclusive with initial_occurrence_estimate_id.
    }
  ],
  "customfields": [// nullable | array | description: array of custom fields
    {
      "id",// nullable | required, if field_instance_id is not set | integer | existing custom field instance id
      "field_instance_id",// nullable | required, if id is not set | integer | existing custom field instance id
      "value",// nullable | description: must match the custom field type when set
    }
  ],
  "template_id",// nullable | integer | existing maintenance agreement template id
  "engage_call_to_records": [// optional | array | description: create only. At most one item may be the primary call.
    {
      "engage_call_id",// required | string | max:255
      "is_primary_call",// nullable | boolean
      "lead_source_id",// nullable | integer | existing lead source id
    }
  ]
}
```


## OpenAPI

````yaml post /maintenance-agreements
openapi: 3.0.0
info:
  title: FieldPulse API
  description: >-
    REST API for the FieldPulse field service management platform.


    **Authentication:** All requests require an `x-api-key` header. Contact
    support@fieldpulse.com to obtain your API key.


    **Important:** The API Playground below makes live requests against your
    production data. Use caution when testing write operations (POST, PUT,
    DELETE).
  version: 1.0.0
servers:
  - url: https://ywe3crmpll.execute-api.us-east-2.amazonaws.com/stage
    description: Production
security:
  - apiKeyAuth: []
tags:
  - name: Assets
    description: Endpoints related to assets
  - name: Assets Category
    description: Endpoints related to assets category
  - name: Comments
    description: Endpoints related to comments
  - name: Company Profile
    description: Endpoints related to contracts
  - name: Contracts
    description: Endpoints related to contracts
  - name: Customers
    description: Endpoints related to customers
  - name: Custom Fields
    description: Endpoints related to custom fields
  - name: Estimates
    description: Endpoints related to estimates
  - name: Invoices
  - name: Items
  - name: Jobs
  - name: Lead Source
  - name: Locations
  - name: Maintenance Agreements
  - name: Material Lists
  - name: Payments
  - name: Pipeline Status
  - name: Projects
  - name: Purchase Orders
  - name: Subtasks
  - name: Tags
  - name: Teams
  - name: Timesheets
  - name: Users
  - name: Vendors
  - name: Version
paths:
  /maintenance-agreements:
    post:
      tags:
        - Maintenance Agreements
      summary: Create Maintenance Agreement
      operationId: postMaintenanceAgreements
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                customer_id:
                  type: integer
                  nullable: true
                  description: >-
                    Required if is_template is false or not set. Existing
                    customer id. Prohibited when is_template is true.
                title:
                  type: string
                  maxLength: 255
                status_id:
                  type: integer
                  description: >-
                    Object type maintenance_agreement. Existing custom status
                    id.
                status_workflow_id:
                  type: integer
                  nullable: true
                  description: >-
                    Object type maintenance_agreement. Existing status workflow
                    id.
                customer_contact_id:
                  type: integer
                  nullable: true
                  description: >-
                    Existing customer contact id. Prohibited when is_template is
                    true.
                parent_invoice_id:
                  type: integer
                  nullable: true
                  description: >-
                    Not a template, and the agreement customer when a customer
                    is set. Existing invoice id.
                timezone:
                  type: string
                  nullable: true
                  description: PHP timezone identifier.
                start_time:
                  type: integer
                  nullable: true
                  description: Timestamp. A date string is also accepted.
                end_time:
                  type: integer
                  nullable: true
                  description: >-
                    Timestamp, same as or after start_time. A date string is
                    also accepted.
                job_location:
                  type: string
                  nullable: true
                  maxLength: 255
                agreement_notes:
                  type: string
                  nullable: true
                job_notes:
                  type: string
                  nullable: true
                is_template:
                  type: boolean
                  nullable: true
                asset_ids:
                  type: array
                  items:
                    type: integer
                  nullable: true
                  description: Array of existing asset ids.
                settings:
                  type: array
                  items: {}
                  nullable: true
                  description: Stored as sent. No child-key rules.
                tags:
                  type: array
                  items:
                    type: integer
                  nullable: true
                  description: >-
                    Tag ids, or objects {"id": tag id}. Type must be
                    maintenance_agreement.
                assignments:
                  type: array
                  items:
                    type: object
                    properties:
                      team_id:
                        type: integer
                        description: Existing team id.
                    required:
                      - team_id
                  nullable: true
                  description: >-
                    Teams only. Each team is expanded to one assignment per
                    member.
                location_id:
                  type: integer
                  nullable: true
                  description: >-
                    A location of the agreement customer. Existing location id.
                    Prohibited when is_template is true.
                parent_job_id:
                  type: integer
                  nullable: true
                  description: >-
                    Not a template, and the agreement customer when a customer
                    is set. Existing job id.
                services_routines:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: integer
                        nullable: true
                        description: Omit to create. Existing service routine id.
                      title:
                        type: string
                        maxLength: 255
                      rrule:
                        type: string
                        nullable: true
                        description: Valid rrule. Required if type is scheduled.
                      type:
                        type: string
                        enum:
                          - scheduled
                          - on-demand
                      asset_ids:
                        type: array
                        items:
                          type: integer
                        nullable: true
                        description: Array of existing asset ids.
                      schedule_generation_method:
                        type: object
                        properties:
                          creation_method:
                            type: string
                            nullable: true
                            enum:
                              - manual
                              - automatic
                            description: Required if schedule_generation_method is set.
                          automatic_creation_method:
                            type: string
                            enum:
                              - automatic
                              - find-availability
                              - fixed
                            description: Required if schedule_generation_method is set.
                          generation_window_in_month:
                            type: integer
                            enum:
                              - 1
                              - 2
                              - 3
                              - 6
                              - 12
                              - 13
                              - 18
                              - 24
                            description: Required if schedule_generation_method is set.
                          set_job_template:
                            type: boolean
                            nullable: true
                            description: >-
                              Must be true when automatic_creation_method is
                              fixed.
                          job_template_id:
                            type: integer
                            nullable: true
                            description: >-
                              Required if set_job_template is true. Existing job
                              template id.
                          fixed_method_rrule:
                            type: string
                            nullable: true
                            description: >-
                              Valid rrule with no start or end. Required if
                              automatic_creation_method is fixed.
                          scheduled_details:
                            type: array
                            items: {}
                            nullable: true
                            description: >-
                              Stored as sent. No child-key rules. Required if
                              automatic_creation_method is find-availability.
                        description: >-
                          Required if type is scheduled. Prohibited, if type is
                          on-demand.
                      on_demand_generation_method:
                        type: object
                        properties:
                          generation_window_in_month:
                            type: integer
                            minimum: 1
                            description: Required if on_demand_generation_method is set.
                          amount_of_services:
                            type: integer
                            minimum: 1
                            description: Required if on_demand_generation_method is set.
                          unused_services_policy:
                            type: string
                            enum:
                              - expire
                              - rollover
                            description: Required if on_demand_generation_method is set.
                          set_job_template:
                            type: boolean
                            nullable: true
                          job_template_id:
                            type: integer
                            nullable: true
                            description: >-
                              Required if set_job_template is true. Existing job
                              template id.
                        description: >-
                          Required if type is on-demand. Prohibited, if type is
                          scheduled.
                      initial_occurrence_job_id:
                        type: integer
                        nullable: true
                        description: >-
                          Create only. The job already booked for the first
                          occurrence. Existing job id.
                    required:
                      - title
                      - type
                  maxItems: 5
                  description: >-
                    Full list. An active agreement requires at least one. A
                    scheduled routine cannot carry on_demand_generation_method.
                    An on-demand routine cannot carry
                    schedule_generation_method. Required if billing_routines is
                    not set.
                services_routine_overlaps:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: integer
                        nullable: true
                        description: Existing overlap id.
                      first_routine_index:
                        type: integer
                        minimum: 0
                        description: Index in services_routines.
                      second_routine_index:
                        type: integer
                        minimum: 0
                        description: >-
                          A different services_routines index. The pair may
                          appear only once.
                      generation_method:
                        type: object
                        properties:
                          creation_method:
                            type: string
                            nullable: true
                            enum:
                              - manual
                              - automatic
                          automatic_creation_method:
                            type: string
                            enum:
                              - automatic
                              - find-availability
                              - fixed
                          generation_window_in_month:
                            type: integer
                            enum:
                              - 1
                              - 2
                              - 3
                              - 6
                              - 12
                              - 13
                              - 18
                              - 24
                          set_job_template:
                            type: boolean
                            nullable: true
                            description: >-
                              Must be true when automatic_creation_method is
                              fixed.
                          job_template_id:
                            type: integer
                            nullable: true
                            description: >-
                              Required if set_job_template is true. Existing job
                              template id.
                          fixed_method_rrule:
                            type: string
                            nullable: true
                            description: >-
                              Valid rrule with no start or end. Required if
                              automatic_creation_method is fixed.
                          scheduled_details:
                            type: array
                            items: {}
                            nullable: true
                            description: >-
                              Stored as sent. No child-key rules. Required if
                              automatic_creation_method is find-availability.
                        required:
                          - automatic_creation_method
                          - generation_window_in_month
                    required:
                      - first_routine_index
                      - second_routine_index
                      - generation_method
                  description: >-
                    Dropped unless both indexed routines are scheduled and
                    creation_method is automatic. One overlap per pair.
                communication:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: integer
                        nullable: true
                        description: Existing communication trigger id.
                      send_type:
                        type: string
                        enum:
                          - email
                          - sms
                      target_routine_mode:
                        type: string
                        enum:
                          - all
                          - multiple
                          - single
                      type:
                        type: string
                        nullable: true
                        enum:
                          - reminder
                          - renewal
                      routine_indexes:
                        type: array
                        items: {}
                        nullable: true
                        description: >-
                          Services_routines indexes. Exactly one when
                          target_routine_mode is single. Not checked when
                          target_routine_mode is all. Required if
                          target_routine_mode is single or multiple.
                      notify_before_date_in_days:
                        type: integer
                        minimum: 0
                      scheduled_statuses:
                        type: array
                        items: {}
                        nullable: true
                        description: >-
                          Acceptable values
                          draft,unscheduled,scheduled,completed,failed. Stored
                          as a comma-separated string.
                      user_to_send:
                        type: array
                        items:
                          type: integer
                        nullable: true
                        description: >-
                          Array of existing user ids. Stored as a
                          comma-separated string.
                      email_subject:
                        type: string
                        nullable: true
                        maxLength: 255
                        description: Required if send_type is email.
                      body:
                        type: string
                      send_to_users:
                        type: boolean
                      send_to_customer:
                        type: boolean
                    required:
                      - send_type
                      - target_routine_mode
                      - notify_before_date_in_days
                      - body
                      - send_to_users
                      - send_to_customer
                  description: Full list. Triggers omitted from the payload are deleted.
                billing_routines:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: integer
                        nullable: true
                        description: Existing billing routine id.
                      title:
                        type: string
                        maxLength: 255
                      creation_method:
                        type: string
                        enum:
                          - manual
                          - recurring-billing
                      rrule:
                        type: string
                        nullable: true
                        description: Valid rrule. Required if creation_method is manual.
                      recurring_billing_id:
                        type: integer
                        nullable: true
                        description: >-
                          Required if creation_method is recurring-billing.
                          Prohibited, if creation_method is manual. Existing
                          recurring billing id.
                      price_per_bill:
                        type: number
                        minimum: 0
                      generation_window_in_month:
                        type: integer
                        minimum: 1
                      initial_occurrence_estimate_id:
                        type: integer
                        nullable: true
                        description: >-
                          Mutually exclusive with initial_occurrence_invoice_id.
                          Existing estimate id.
                      initial_occurrence_invoice_id:
                        type: integer
                        nullable: true
                        description: >-
                          Create only. Mutually exclusive with
                          initial_occurrence_estimate_id. Existing invoice id.
                    required:
                      - title
                      - creation_method
                      - price_per_bill
                      - generation_window_in_month
                  maxItems: 1
                  description: An active agreement requires exactly one.
                customfields:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: integer
                        nullable: true
                        description: >-
                          Required if field_instance_id is not set. Existing
                          custom field instance id.
                      field_instance_id:
                        type: integer
                        nullable: true
                        description: >-
                          Required if id is not set. Existing custom field
                          instance id.
                      value:
                        type: string
                        nullable: true
                        description: Must match the custom field type when set.
                  nullable: true
                  description: Array of custom fields.
                template_id:
                  type: integer
                  nullable: true
                  description: Existing maintenance agreement template id.
                engage_call_to_records:
                  type: array
                  items:
                    type: object
                    properties:
                      engage_call_id:
                        type: string
                        maxLength: 255
                      is_primary_call:
                        type: boolean
                        nullable: true
                      lead_source_id:
                        type: integer
                        nullable: true
                        description: Existing lead source id.
                    required:
                      - engage_call_id
                  description: Create only. At most one item may be the primary call.
              required:
                - title
                - status_id
            example:
              customer_id: 1
              title: some string
              status_id: 1
              status_workflow_id: 1
              customer_contact_id: 1
              parent_invoice_id: 1
              timezone: some string
              start_time: 1
              end_time: 1
              job_location: some string
              agreement_notes: some string
              job_notes: some string
              is_template: true
              asset_ids:
                - 1
              settings: []
              tags:
                - 1
              assignments:
                - team_id: 1
              location_id: 1
              parent_job_id: 1
              services_routines:
                - id: 1
                  title: some string
                  rrule: some string
                  type: scheduled
                  asset_ids:
                    - 1
                  schedule_generation_method:
                    creation_method: manual
                    automatic_creation_method: automatic
                    generation_window_in_month: 1
                    set_job_template: true
                    job_template_id: 1
                    fixed_method_rrule: some string
                    scheduled_details: []
                  on_demand_generation_method:
                    generation_window_in_month: 1
                    amount_of_services: 1
                    unused_services_policy: expire
                    set_job_template: true
                    job_template_id: 1
                  initial_occurrence_job_id: 1
              services_routine_overlaps:
                - id: 1
                  first_routine_index: 1
                  second_routine_index: 1
                  generation_method:
                    creation_method: manual
                    automatic_creation_method: automatic
                    generation_window_in_month: 1
                    set_job_template: true
                    job_template_id: 1
                    fixed_method_rrule: some string
                    scheduled_details: []
              communication:
                - id: 1
                  send_type: email
                  target_routine_mode: all
                  type: reminder
                  routine_indexes: []
                  notify_before_date_in_days: 1
                  scheduled_statuses: []
                  user_to_send:
                    - 1
                  email_subject: some string
                  body: some string
                  send_to_users: true
                  send_to_customer: true
              billing_routines:
                - id: 1
                  title: some string
                  creation_method: manual
                  rrule: some string
                  recurring_billing_id: 1
                  price_per_bill: 1
                  generation_window_in_month: 1
                  initial_occurrence_estimate_id: 1
                  initial_occurrence_invoice_id: 1
              customfields:
                - id: 1
                  field_instance_id: 1
                  value: some string
              template_id: 1
              engage_call_to_records:
                - engage_call_id: some string
                  is_primary_call: true
                  lead_source_id: 1
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: boolean
                    description: false when the request succeeds.
                    example: false
                  response:
                    type: object
              example:
                error: true
                errors:
                  - error message
                  - error message
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````

## Related topics

- [User Roles and Permissions Details](https://help.fieldpulse.com/settings/users-teams/user-roles.md)
- [How to Create a Maintenance Agreement](https://help.fieldpulse.com/jobs/assets/maintenance-agreements.md)
- [How to Create Maintenance Agreement Reports](https://help.fieldpulse.com/reporting/raw-data/maintenance-agreement-reports.md)
- [Maintenance Agreements Overview](https://help.fieldpulse.com/jobs/assets/maintenance-agreements-overview.md)
- [Setting Up Maintenance Agreement Automation](https://help.fieldpulse.com/jobs/assets/maintenance-agreement-automation.md)


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