> For the complete documentation index, see [llms.txt](https://docs.platform.softwareone.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.platform.softwareone.com/developer-resources/api-usage-and-reference/common-api-objects/externalids.md).

# 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</th><th width="121">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 title="EXTERNAL ID OBJECT" 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.platform.softwareone.com/developer-resources/api-usage-and-reference/common-api-objects/externalids.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.