---
title: "Create or update an external reference"
method: POST
path: "/external_references/create_or_update"
tags: ["External References"]
---

# Create or update an external reference

`POST /external_references/create_or_update`

## Request

- Base URL: `https://api.mavenlink.com/api/v1`
- URL: `https://api.mavenlink.com/api/v1/external_references/create_or_update`
- Auth: none declared

This endpoint returns structured External Reference objects.
As with all Kantata OX API endpoints, the returned data will be referenced in sorted order in the `results` array
and will be indexed by ID in the `external_references` top-level JSON key.
Please see our [Response Format](#section/Response-Format) section for more information.

## Query parameters

- `include` string

## Request body

- object
  - `external_reference` object
    - `subject_type` string, required: The type of the Kantata OX object to which this external reference belongs. One of `Assignment`, `BillingMilestone`, `CustomField`, `CustomFieldChoice`, `CustomFieldSet`, `CustomFieldValue`, `Estimate`, `EstimateScenario`, `EstimateScenarioResource`, `Expense`, `ExpenseBudget`, `Invoice`, `Participation`, `Post`, `RateCard`, `Role`, `Skill`, `StatusReport`, `Story`, `StoryAllocationDay`, `Submission`, `SurveyAnswer`, `SurveyQuestion`, `SurveyResponse`, `SurveyTemplate`, `TimeEntry`, `TimeOffEntry`, `User`, `Vendor`, `Workspace`, `WorkspaceAllocation`, `WorkspaceGroup`, or `WorkspaceResource`.
    - `subject_id` integer, required: The ID of the Kantata OX object to which this external reference belongs.
    - `service_name` string, required: The provider name of the integration.
    - `service_model` string, required: The type of the external object to which this reference belongs.
    - `service_model_ref` string, required: The ID of the external object to which this external reference belongs.
    - `status` string: The status of the integration. Options are 'pending', 'successful', or 'failed'.
    - `external_link` string: A URL that links to either the external object or event.
    - `external_status` string: The status of the external object in the external system.
    - `external_message` string: An optional message about the external object.
    - `locked` boolean: An optional field, indicates whether the subject should be locked. To prevent changes to the object in Kantata OX, set this to true. This currently only applies to expense report rejections.

## Response `200`

External Reference has been created.

- object
  - `count` integer
  - `meta` object
    - `count` integer
    - `page_count` integer
    - `page_number` integer
    - `page_size` integer
  - `results` object[]
    - `key` string
    - `id` string
  - `external_references` object
  - `assignments` object
  - `billing_milestones` object
  - `custom_fields` object
  - `custom_field_choices` object
  - `custom_field_sets` object
  - `custom_field_values` object
  - `estimates` object
  - `estimate_scenarios` object
  - `estimate_scenario_resources` object
  - `expenses` object
  - `expense_budgets` object
  - `invoices` object
  - `participations` object
  - `posts` object
  - `rate_cards` object
  - `roles` object
  - `skills` object
  - `status_reports` object
  - `stories` object
  - `story_allocation_days` object
  - `submissions` object
  - `survey_answers` object
  - `survey_questions` object
  - `survey_responses` object
  - `survey_templates` object
  - `time_entries` object
  - `time_off_entries` object
  - `users` object
  - `vendors` object
  - `workspaces` object
  - `workspace_allocations` object
  - `workspace_groups` object
  - `workspace_resources` object

## Other responses

- `400`: Bad Request
- `401`: Unauthorized request
- `403`: Forbidden request
- `404`: Page Not Found
- `422`: Unprocessable Entity
- `503`: Service is unavailable

---

[API](https://skmtc.dev/kantata/apis/kantata-ox-api-documentation.md) - [All operations](https://skmtc.dev/kantata/apis/kantata-ox-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/kantata/apis/kantata-ox-api-documentation/revisions/9d4ebed2fa98?raw)