POST /records service enables to register an ISAN work ( series, group (i.e season), episode, single), or an ISAN version (variant, manifestation, related content, related item).
The following topics are covered in this article:
- Single work applications
- Episodic work applications: series, group, episode records
- Checking Application Status
- Manage pending applications (deduplication process)
- Retrieving the Allocated ISAN
All along this article, you can refer to ISAN swagger site for details and examples in json and xml
1. Single work applications
The registration process for a single work follows four main steps:
Step 1: Submit the Work Data
Send a POST /records request to register or validate a record.
- Reference: Consult the ISAN Swagger interface for JSON/XML examples.
-
Authentication: Ensure you are logged in (lock icon) and have set the
X-ISAN-Authorizationtoken.
Note: Avoid Conflicts with Examples, indeed, Data Swagger examples often use data already registered by other users, which will trigger errors or pending states. Before sending your request:
-
Unique
recordId: Change therecordIdto a value unique to your user account. - Unique Metadata: Modify metadata fields (titles, dates, etc.) to ensure the work is not flagged as a potential duplicate.
- Linked ISANs: Remove or replace any linked ISANs in the examples with valid ISANs existing in your sandbox or production database.
Step 2: Check Application Status
After submission, verify the status of your application.
Step 3: Handle Deduplication (If Pending)
If the status returns as pending, the system has found potential matches.
Step 4: Retrieve the ISAN
Once the status is active (new ISAN) or duplicate (existing ISAN), you can retrieve the identifier.
- Action: Get the newly allocated ISAN
2. Episodic work applications: series, group, episode records
Registering episodic content requires a specific hierarchy. Parents must be registered before children.
2.1 Hierarchy Rules
- Series First: You must register the Series record first. Note: The Series ISAN is not issued at this stage.
- Child Second: Register a child record (Group/Season or Episode) linked to the Series.
- ISAN Issuance: The Series ISAN is only allocated after the first child record is successfully registered.
⚠️ Validation Warnings
- Parent Dependency: A Group cannot be registered without a Series. An Episode cannot be registered without a Series and/or Group.
-
Validation Errors: Attempting to validate a child record before its parent exists will fail because the
parentRecordIdis unknown to the system.
2.2 Registration Workflow
Step 1: submit the series Data
-
POST /recordswith Series metadata. -
Apply the same uniqueness warnings regarding
recordIdand metadata as in Single Work Applications.
Step 2: Check Series Status
- Verify the status (likely
waiting_for_child).
Step 3: Series Deduplication (if pending)
- If the series application status is
pending: deduplicate before submit Child Data Manage pending applications: deduplication process
Step 4: Submit First Child Data (Group or Episode)
-
POST /recordswith the child metadata, linking it to the SeriesrecordId. -
Ensure
recordIdand metadata are unique.
Step 5: Check Child Status
- Verify the status of the child application. Handle deduplication if
pending.
Step 6: Child Deduplication (if pending)
- If the status is
pending: deduplicate child Child Data application Manage pending applications: deduplication process
Step 7: Retrieve ISANs
- Once both applications are
active, retrieve the ISANs. Both the Series and the Child will now have allocated ISANs.
Step 8: Register other Seasons and Episodes
- Once the first child is registered, you can register additional seasons and episodes starting from above Step 4
3. Get the Status of the ISAN Application
Use the /myisan service to query your client catalogue for registered ISANs and application statuses. The search scope is restricted to your own catalogue.
3.1 Query Example
To check the status of recordId = 123456 with POST /myisan:
json
{
"sortBy": "relevance",
"order": "desc",
"scope": "user_catalog",
"page": 0,
"size": 10,
"fields": ["status"],
"recordId": "123456"
}
3.2 Response Example
json
(...)
"results": [
{
"status": {
"recordKind": "episode",
"ISAN": {
"value": "0000-0004-6772-0038-4-0000-0000-P"
},
"recordStatus": "active",
"activeIsan": {
"value": "0000-0007-13C9-0000-8-0000-0000-D"
}
}
}
]3.3 Status Definitions
| Status | Description |
|---|---|
submitted |
Application submitted; awaiting processing. |
in_progress |
Application is currently being processed. |
pending |
Manual deduplication required (potential match found). |
waiting_for_child |
On hold until a child record is provided (e.g., Series waiting for Episode). |
waiting_for_parent |
On hold until a parent record is registered (e.g., Episode waiting for Series). |
active |
ISAN successfully allocated. |
duplicate |
Application resolved as a duplicate; linked to an existing ISAN. |
inactive |
ISAN inactivated (aliased) due to a correction during Quality Control. |
3.4 Search Methods
- Record-based Search (
POST /myisan): Query using specific record data. - Query-based Search (
GET /myisan): Build a search query using parameters. -
Tips:
- Set
fieldstostatusfor lightweight status checks. - Repeatable arguments (countries, languages) form an
ORcondition.
- Set
4. Manage pending applications (deduplication process)
A status of pending indicates the application matches one or more active ISANs. Manual intervention is required to confirm if it is a true duplicate or a new work.
Step 1: List Matching Candidates
Use the /deduplication service to retrieve potential matches for your recordId.
Request Example (JSON):
json
{
"sortBy": "relevance",
"page": 0,
"size": 10,
"recordId": "test-0001",
"fields": ["titles", "status", "participants"]
}
Step 2: Resolve the Deduplication
Invoke the service with your recordId and specify an action.
Option A: New Work (is_new) None of the candidates match. A new ISAN will be issued.
json
{
"recordId": "test-0001",
"action": "is_new"
}
Option B: Duplicate (is_duplicate) The work already exists. Link the application to the existing ISAN.
json
{
"recordId": "test-0001",
"action": "is_duplicate",
"candidates": [
{
"ISAN": "0000-0006-2061-0000-F-0000-0000-T",
"comment": "",
"type": ""
}
]
}
Option C: New Work with Link (is_new_and_link_isan) The work is new, but related to an existing ISAN (e.g., a sequel). A new ISAN is issued and linked.
json
{
"recordId": "test-0001",
"action": "is_new_and_link_isan",
"candidates": [
{
"ISAN": "0000-0006-2061-0000-F-0000-0000-T",
"type": "sequel",
"comment": ""
}
]
}
5. Retrieving the Allocated ISAN
POST /myisan or GET /myisan: Once the application status is active (new ISAN) or duplicate (existing ISAN), the identifier is available in the status object.
Retrieval Strategies
- Lightweight Retrieval: Set
fieldstostatus. This returns only the status and ISAN values. - Full Data Retrieval: Set
fieldstoallRecordDatato retrieve all metadata associated with the ISAN.
❗ Critical: Handling Inactive ISANs
During Quality Control, a mistakenly created duplicate ISAN may be inactivated (aliased) in favor of the original active ISAN.
- Risk: If you query with
allRecordData, theISANfield might contain the inactive (deprecated) value. - Solution: Always extract the valid identifier from the
activeIsanfield within thestatusobject. This guarantees you receive the currently active ISAN, even if the specific application record was later inactivated.
Example Response with Inactivation:
json
"results": [
{
"status": {
"recordKind": "episode",
"ISAN": {
"value": "0000-0004-6772-0038-4-0000-0000-P" // Inactive ISAN
},
"recordStatus": "inactive",
"activeIsan": {
"value": "0000-0007-13C9-0000-8-0000-0000-D" // ✅ Use this value
},
"description": "This ISAN ... has been inactivated. Please use the ISAN ..."
}
}
]