# External IDs

The `External IDs` object contains a set of external identifiers.

External IDs are assigned during a `PUT` (update) or `POST` (create) request. Clients can update only their own external IDs, vendors can update only their own external IDs, and SoftwareOne Operations can update only the ID related to their specific operation.

<table><thead><tr><th width="224">Field Name</th><th width="121">Data Type</th><th>Description</th></tr></thead><tbody><tr><td><code>externalIds.client</code></td><td>string</td><td>The client-specific external ID, visible to clients.</td></tr><tr><td><code>externalIds.operations</code></td><td>string</td><td>The operations-specific external Id, visible to operations.</td></tr><tr><td><code>externalIds.vendor</code></td><td>string</td><td>The vendor-specific external Id, visible for vendors.</td></tr></tbody></table>

{% code lineNumbers="true" %}

```json
{
  "client": "12345678",
  "operations":	"07bf766b-c767-4293-9ab3",
  "vendor": "ABC-2023-C07-dbeee0b302c0"
}
```

{% endcode %}

## Semantics and typical usage

Many resources (agreements, orders, subscriptions, etc.) expose a `externalIds` property. It stores key identifiers from actors that interact with the object but are not part of the marketplace (vendor, client, operations). Each actor can set and see only their own key; the meaning of each key depends on the resource and the actor.

* `externalIds.vendor` - On agreements and related resources, the vendor often stores the external unique identifier of the contract in their system (for example, Microsoft account ID, Adobe client ID). Use it to correlate platform objects with vendor-side contracts or systems.
* `externalIds.client` - The client can use this for programmatic access or to store a reference that matters on their side (for example, blanket order ID, open order ID, or an internal reference). Useful when looking up an order or agreement "by our reference" or "by our ID".
* `externalIds.operations` - Used by SoftwareOne operations for their own identifiers and processes.

Which keys exist and who can read/write them depends on the resource and the caller; check the resource schema and visibility rules. To filter by an external ID in RQL, use the field path (for example) `eq(externalIds.vendor,"ABC-123")` or `eq(externalIds.client,"my-ref-456")`) when the resource exposes it.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.platform.softwareone.com/developer-resources/rest-api/common-api-objects/externalids.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.