Skip to main content
Sign in

ISAN API 3.0 - ISAN Data Update Services

Régis Flad
  • Updated

The ISAN Registry provides two distinct methods for updating metadata: Partial Update(recommended) and Full Update (restricted use).

1. Partial Data Update (Recommended)

Endpoint: PATCH /records
Method: Update individual parts of the data associated with an ISAN.

PATCH /records Update individual parts of the data associated with an ISAN

Overview

Use this service to add, update, or delete specific information associated with an ISAN. ISAN-IA strongly recommends this method for all data updates to prevent potential data corruption in the ISAN registry.

Documentation: Refer to the ISAN Swagger interface for detailed parameter definitions and examples in JSON and XML.

Prerequisites

  • Authorization: The API user must have a Registrant role or be a Registration Agency user (X-ISAN-Authorization).
  • Ownership: The record to be updated must exist in the user’s catalogue.

Operation Logic

This service supports ADD and DELETE operations. A single request can contain both an ADDblock and a DELETE block, each listing the fields to which the operation applies.

How to Perform Updates

Field Type Examples Update Procedure
Repeatable Fields Titles, Participants, Countries, linkedIds, ... Delete then Add: To update values, you must first DELETE the old values and ADD the new ones. Both operations can be performed simultaneously in the same request.
Non-Repeatable Fields Duration, Release Date

Add (Overwrite): Simply ADD the new value; it will overwrite the previous one.

⚠️ DELETE operations are not permitted on mandatory non-repeatable fields.

 

2. Full Data Update (Restricted)

Endpoint: PUT /records
Method: Update all metadata associated with an ISAN.

PUT /records Update all metadata associated with an ISAN

Overview

⚠️ Warning: This service is intended primarily for quality management purposes (e.g., bulk corrections by Registration Agencies).

For standard data updates, always prefer the Partial Update (PATCH) method. If you must implement this service, exercise extreme caution: the request replaces the entire metadata record. Any field omitted in the request may be lost or reset.

Critical Prohibition

🛑 Do Not Refactor Active ISANs:
It is strictly forbidden to change the core metadata of an active ISAN to associate it with a completely different work. Doing so creates major conflicts and confusion in any system that has already referenced this ISAN. An ISAN is a permanent identifier for a specific work; it cannot be reassigned.

Prerequisites

  • Authorization: The API user must have a Registrant role or be a Registration Agency user (X-ISAN-Authorization).
  • Ownership: The record to be updated must exist in the user’s catalogue.

Documentation: Refer to the ISAN Swagger interface for full payload structures and examples in JSON and XML.

 

 

Related articles