ISAN API 3.0 - New ISAN Applications

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:

1. Single work applications
2. Episodic work applications: series, group, episode records
3. Checking Application Status
4. Manage pending applications (deduplication process) 
5. 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-Authorization token.

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 the recordId to 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.

• Action: Get the status of the ISAN application

Step 3: Handle Deduplication (If Pending)

If the status returns as pending, the system has found potential matches.

• Action: Manage pending applications: deduplication process

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

1. Series First: You must register the Series record first. Note: The Series ISAN is not issued at this stage.
2. Child Second: Register a child record (Group/Season or Episode) linked to the Series.
3. 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 parentRecordId is unknown to the system.

2.2 Registration Workflow

Step 1: submit the series Data

• POST /records with Series metadata.
• Apply the same uniqueness warnings regarding recordId and 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 /records with the child metadata, linking it to the Series recordId.
• Ensure recordId and 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

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 fields to status for lightweight status checks. 
  • Repeatable arguments (countries, languages) form an OR condition.

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.

json

{
  "recordId": "test-0001",
  "action": "is_new"
}

json

{
  "recordId": "test-0001",
  "action": "is_duplicate",
  "candidates": [
    {
      "ISAN": "0000-0006-2061-0000-F-0000-0000-T",
      "comment": "",
      "type": ""
    }
  ]
}

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

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 ..."
      }
   }
]