# Create or update an external reference

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 for more information.

Endpoint: POST /external_references/create_or_update
Version: 1.0.0

## Query parameters:

  - `include` (string)
    Any of the below associations can be included in your request by providing the include param, e.g. include=association1,association2.
- subject (polymorphic) - The item with which the external reference is associated.

## Request fields (application/json):

  - `external_reference` (object)

  - `external_reference.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.

  - `external_reference.subject_id` (integer, required)
    The ID of the Kantata OX object to which this external reference belongs.

  - `external_reference.service_name` (string, required)
    The provider name of the integration.

  - `external_reference.service_model` (string, required)
    The type of the external object to which this reference belongs.

  - `external_reference.service_model_ref` (string, required)
    The ID of the external object to which this external reference belongs.

  - `external_reference.status` (string)
    The status of the integration. Options are 'pending', 'successful', or 'failed'.

  - `external_reference.external_link` (string)
    A URL that links to either the external object or event.

  - `external_reference.external_status` (string)
    The status of the external object in the external system.

  - `external_reference.external_message` (string)
    An optional message about the external object.

  - `external_reference.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 fields (application/json):

  - `count` (integer)

  - `meta` (object)

  - `meta.count` (integer)

  - `meta.page_count` (integer)

  - `meta.page_number` (integer)

  - `meta.page_size` (integer)

  - `results` (array)

  - `results.key` (string)

  - `results.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)

## Response 400 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 401 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 403 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 404 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 422 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 503 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)