Aprimo API

Authentication

Where credentials come from S3

1. An admin with the Security or System Administration domain right opens Administration → Integration → Registrations and creates a registration: name, description, Client Secret (cannot be retrieved later), redirect URL (code flows), OAuth Flow Type, access-token lifetime, optional refresh token.
2. For Client Credentials the registration names the user on whose behalf all calls run (the only user for that registration).
3. Changes can take up to 15 minutes to propagate S3 S14.

Flows

• The login service is an OpenID Connect provider: discovery at https://{tenant}.aprimo.com/login/.well-known/openid-configuration advertises authorization_code, client_credentials, refresh_token, password, implicit, device-code, CIBA and token-exchange grants, PKCE plain/S256, client auth client_secret_basic/client_secret_post/private_key_jwt, and no dynamic client registration endpoint S40. Only the flows in the table above are documented S3.
• Service users and admin rights: in PM, users with System Administration, Access cannot read/edit records via the API; the Integration API, Access domain right lets a service user bypass PM access lists (activities, programs, funding accounts, markets, plans, offers) S3. For the DAM, visibility is governed by the represented user's DAM permissions and classification permissions S16 S22.
• Sending the token: Authorization: Bearer <token> on every call; a 401 with an empty body usually means an expired token S3. X-Access-Token is not used by any current documented flow; the legacy exchange-auth-code route that used it is deprecated S18.

Required DAM headers S16

Core resources

Paths relative to https://{tenant}.dam.aprimo.com/api/core. Inventory from the full OpenAPI spec (48 tags, 312 operations) S16; examples in Postman S17.

Data model

• Record = the central object (an asset, or content without a file). Fields: id, status ∈ Draft, Released, Archived, Unpublished (out-of-box), contentType, title, tag, textContent, aIInfluenced, hasImageOverlay, createdOn, modifiedOn; related data are not returned unless selected S6 S16.
• Identifiers are GUIDs; examples are shown both with and without hyphens (e.g. 250d22a231ed4f0ba9afa49900b0252e) S16. Whether hyphenated GUIDs are accepted on every route is Unknown Unverified.
• Selecting (expansion): select-{resource} headers embed relations, e.g. select-record: fields, classifications, masterfilelatestversion, preview, thumbnail, permissions, locks, accesslists, analyticsdata, createdby, modifiedby; nested selectors such as select-field: definition, select-fileversion: renditions, publiclinks, additionalfiles, filepreviews, select-classification: parent, children; select-record-fields / select-record-fieldgroups restrict fields by ID or name; select-resolve-default-values: false omits default values. A resource type may occur at most twice in an embedding chain; selecting a missing relation embeds null, following its link returns 404 S8 S16. Valid select keys are listed as select-key in HAL _links S6 S8.
• Metadata: FieldDefinition with dataType ∈ SingleLineText, MultiLineText, Numeric, DateTime, Date, Time, OptionList, Duration, UserList, UserGroupList, Html, Json, ClassificationList, RecordList, RecordLink, LanguageList, TextList, HyperlinkList (18 types) S16; properties include scope/scopeCategory (e.g. RecordContentGlobal, record vs classification vs user fields), languageMode (Single/Multiple), indexed, isRequired, defaultValue, validation S7 S16. Values are localized: fields.items[].localizedValues[{languageId, value | values[] | hyperlinks[]}]; option values are option IDs S16 S20 S36.
• Field applicability: a field becomes usable on a record when registered on one of its classifications (scope "Record Content Class Dependent") and/or its content type; UI visibility also needs the DAM UI JSON layout S11.
• Taxonomy = classifications, a tree (parent, children, ancestors, NamePath/LabelPath, Identifier, SortIndex) that also carries registered fields, record/tree/download permissions and download agreements S7 S16.
• Files: record → files (master + others) → file versions (checksum CRC32, extension, file type) → renditions, additional files (crops, trims, renditions), previews, public links S7 S12 S16.
• Languages: fetch /languages and cache; request localized values with header languages: {id}[,{id}] or *; default = the calling user's language S16.
• Editing: PUT is partial (send only what changes; null usually resets); nested collections use {addOrUpdate:[…], remove:[…]}; the JSON returned by a read can generally be reused as the edit body S16 S36.

Search & querying

S7 S16 unless noted.

Uploads & binaries

Upload flow (Upload Service, https://{tenant}.aprimo.com/uploads) S16 S35

1. < 20 MB: POST/uploads multipart/form-data, one file per request → 200 {token, sasUrl} (or 202). Requires the user to hold .RoleExecuteMaintenanceJobs and .RoleViewMaintenanceJobs.
2. > 20 MB: POST/uploads/segments {filename} → {uri, token}; upload zero-based segments ?index=n (parallel allowed) → 202; POST…/commit {filename, segmentcount} → {token, sasUrl}; DELETE… cancels. Aprimo recommends 20 MB chunks S5.
3. Very large files: POST/uploads {fileName} (JSON) returns a writable Azure blob sasUrl for AzCopy; the token is usable once the copy has finished.
4. Attach: POST/records (or PUT/record/{id}) with files.master = <uploadToken> and a version entry, plus at least one classification. Upload tokens are single-use and uploads are purged "after a few days". Unsupported filename characters: < > : " / \ | ? *.
5. Since 2026-06-01 every upload request (including each segment) needs a valid bearer token; upload.aprimo.com is retired S18.

• Metadata can be ingested with a CSV token + .dataExchangeSchemas XML schema in the record-create call S10.

Downloads & renditions S16 S35 S36

• Orders (POST/orders, type: download, targets with recordId, assetType ∈ LatestVersionOfMasterFile, AllVersionsOfMasterFile, LatestVersionOfAllFiles, AllVersionsOfAllFiles, optional transformation actions) are processed asynchronously; poll GET/order/{id} for deliveredFiles. Reading orders requires the ViewMaintenanceJobs role. Synchronous orders exist for untransformed downloads S36.
• Download URIs carry an expiring token: 30 h with disk storage, otherwise at least the value of .minimumAvailableTimeForOrders / .minimumAvailableTimeForPreviews (Azure blob). The URI may redirect (301/302) to the CDN; header Location-Alias selects CDN region us1, eu2, au1, cn1.
• Previews/thumbnails: /record/{id}/image/{preview|thumbnail} (MCP docs describe ~150×150 thumbnails, ~800×600 previews, SAS URLs valid ~24 h) S20.
• Public CDN links: created via an order of type publicCDN (or rules); the URL pattern is set globally so a public URL is known before caching; supports URL transformations; recommended for CMS/e-commerce/email S16 S36 S46.
• Renditions: presets in the .renditionPreset setting, generated by rules or POST/maintenancejobs action CreateRenditions (e.g. AI removeBackground); crops (CropImage) and video trims (TrimVideo) stored as additional files S12.

Events & webhooks

DAM — Rules S29

• If/then rules on records, files, classifications and other objects; triggered on save/delete or on a schedule; actions include field updates, classification linking, renditions/previews/public links, e-mail, AI actions and an HTTP Request action (POST to a configured URI).
• Actions run immediately (before save, under the triggering user's validation) or delayed (maintenance job, bypasses validation); rules are versioned.
• Retries: only some action types support a retries parameter (list Behind login in the in-app help); receivers must answer fast — 2xx, 400 and 500 do not trigger a retry; retries can arrive out of order, so payloads should only announce what changed and the receiver should re-read the API.
• Configuration: DAM UI or Admin Studio; the /rules API endpoints also expose them S16. Payload schema and signing for DAM HTTP actions are Not public in the developer docs; Aprimo's sample integrations authenticate by adding a custom Authorization header in the rule's ref:httpRequest definition S73.
• Content subscriptions (/subscriptions) exist in the spec; their delivery mechanism is not described there S16 Unverified. The rules docs cite e-mailing "subscribed users" about expiring assets as a use case S29.

PM — Webhooks S30

• Events: object created/updated/deleted (supported object list), task status action, project started/paused/resumed/closed/cancelled/role changed, commitment approved/rejected/cancelled, forecast changed, segmentation events, program proposal submitted, content-plan link changes, SSO user created/updated (CalloutLocation 500/501).
• Payload: JSON POST with CalloutLocation, ObjectTypeId, ObjectResourceName, ObjectId, CreatingUserId, RetryCount, Body (string), EventTime, EventId, ParentEventId.
• Security: X-SH1 header = Base64(HMAC-SHA256(body, secret)).
• Delivery: 30 s timeout; up to 4 retries (1, 2, 5, 7, 15 min schedule, exponential backoff with jitter); after 5 consecutive failures the subscription is invalidated and admins notified; manual retry from the Integration Log.

UI page hooks: DAM page hooks POST (or GET with {{field:Name}} URL tokens) to your endpoint with the triggering user's access-token, 15 s default / 30 s max timeout; response can show a message or open a URL S31. PM page hooks exist too S32.

Limits & quirks

SDKs, tools & code samples

Changelog of the API