| Panel | |
|---|---|
|
About the Write API
This API is used to send SOR information to the Identity Registry.
Methods
SOR Person Role Added
It is up to the Identity Registry to determine how to map the provided attributes to its internal data model.
In these examples, hrms is the SOR, X12345 is the SORID, and R98765 and R98766 are SOR Role IDs. 
The SOR Role ID must be unique for the SOR Person, but need not be unique across all SOR Roles.
Request Using Separate Person-Level and Role-Level Attributes
| Code Block |
|---|
PUT /v1/sorPeople/hrms/X12345
{
"sorAttributes":
{
"names":[
{
"type":"official",
"given":"Pat",
"family":"Lee"
}
],
"dateOfBirth":"1983-03-18"
}
}
PUT /v1/sorPeople/hrms/X12345/R98765
{
"sorAttributes":
{
"title":"Professor of Phrenology"
"percentTime":"50%"
}
}
PUT /v1/sorPeople/hrms/X12345/R98766
{
"sorAttributes":
{
"title":"Administrative Assistant"
"percentTime":"20%"
}
}
|
Response
Response | Description |
|---|---|
| Request successfully processed |
| There was a problem with the data submitted |
| Authentication required |
| Client is attempting to operate outside of its authority (eg: to the wrong SOR path); Optional – server may return |
| There is already a person or role with the specified identifer Since Add and Update use the same |
| Unknown error |
The Identity Registry may return a Reference Identifier if identity match is not called separately. (The other ID Match responses may apply, as well.)
| Code Block |
|---|
201 Created
{
"referenceId":"M225127891"
}
|
Additional attributes, such as identifiers, may also be returned, or may be returned instead.
| Code Block |
|---|
201 Created
{
"referenceId":"M225127891",
"identifiers":[
{
"identifier":"pl53",
"type":"network"
}
],
"emailAddresses":[
{
"address":"pat.lee@university.edu",
"type":"official"
}
]
}
|
Request Using Person-Level Attributes Expressed As Role-Level Attributes
In this example, the SOR is capable of representing Person-Level Attributes, but the Identity Registry is not. This example also applies where the Identity Registry is capable of representing Person-Level Attributes, but the SOR is not.
| Code Block |
|---|
PUT /v1/sorPeople/hrms/X12345/R98765
{
"sorAttributes":
{
"names":[
{
"type":"official",
"given":"Pat",
"family":"Lee"
}
],
"dateOfBirth":"1983-03-18"
"title":"Professor of Phrenology"
"percentTime":"50%"
}
}
PUT /v1/sorPeople/hrms/X12345/R98766
{
"sorAttributes":
{
"names":[
{
"type":"official",
"given":"Pat",
"family":"Lee"
}
],
"dateOfBirth":"1983-03-18"
"title":"Administrative Assistant"
"percentTime":"20%"
}
}
|
Requesting Assignment of SORID
To support cases where a Registry is maintaining authoritative records on behalf of an SOR, but the user interface is not provided by the Registry, it is possible to request addition of a record without providing an SORID. It is then up to the Registry to assign a new SORID and return it in the response.
| Code Block |
|---|
POST /v1/sorPeople/guest
{
"sorAttributes":
{
"names":[
{
"type":"official",
"given":"Pat",
"family":"Lee"
}
],
"emailAddresses":[
{
"address":"pat.lee@gmail.com",
"type":"personal"
}
]
}
}
|
| Code Block |
|---|
201 Created
{
"referenceId":"M225127891",
"identifiers":[
{
"identifier":"GUEST000797031",
"type":"sor"
},
{
"identifier":"pl53",
"type":"network"
}
]
}
|
Registries that require the use of role record identifiers will also need to assign and return a role record identifier.
| Code Block |
|---|
201 Created
{
"referenceId":"M225127891",
"identifiers":[
{
"identifier":"1853737",
"type":"role"
},
{
"identifier":"GUEST000797031",
"type":"sor"
},
{
"identifier":"pl53",
"type":"network"
}
]
}
|
To add an additional role to an existing SORID, use the following example. GUEST000797031 is the SOR ID. Note the use of POST to distinguish from an SOR Person Role Add Request Using Separate Person-Level and Role-Level Attributes.
| Code Block |
|---|
POST /v1/sorPeople/guest/GUEST000797031
{
"sorAttributes":
{
"names":[
{
"type":"official",
"given":"Pat",
"family":"Lee"
}
],
"emailAddresses":[
{
"address":"pat.lee@gmail.com",
"type":"personal"
}
]
}
}
|
| Code Block |
|---|
201 Created
{
"referenceId":"M225127891",
"identifiers":[
{
"identifier":"1853738",
"type":"role"
},
{
"identifier":"GUEST000797031",
"type":"sor"
},
{
"identifier":"pl53",
"type":"network"
}
]
}
|
SOR Person Role Deleted
| Code Block |
|---|
DELETE /sorPeople/hrms/X12345/R98765 |
Response
Response | Description |
|---|---|
| Request successfully processed |
| Authentication required |
| Client is attempting to operate outside of its authority (eg: to the wrong SOR path); Optional – server may return |
| The specified person is unknown |
| The specified role is unknown |
| Unknown error |
SOR Person Role Updated
Request Using Separate Person-Level and Role-Level Attributes
| Code Block |
|---|
PUT /v1/sorPeople/hrms/X12345
{
"sorAttributes":
{
"names":[
{
"type":"official",
"given":"Patricia",
"family":"Lee"
}
],
"dateOfBirth":"1983-03-18"
}
}
PUT /v1/sorPeople/hrms/X12345/R98765
{
"sorAttributes":
{
"title":"Professor of Cosmology"
"percentTime":"50%"
}
}
|
Request Using Person-Level Attributes Expressed As Role-Level Attributes
| Code Block |
|---|
PUT /v1/sorPeople/hrms/X12345/R98765
{
"sorAttributes":
{
"names":[
{
"type":"official",
"given":"Pat",
"family":"Lee"
}
],
"dateOfBirth":"1983-03-18",
"title":"Professor of Cosmology"
"percentTime":"50%"
}
}
|
Response
Response | Description |
|---|---|
| Request successfully processed |
| There was a problem with the data submitted |
| Authentication required |
| Client is attempting to operate outside of its authority (eg: to the wrong SOR path) |
| The specified person is unknown Since Add and Update use the same |
| The specified role is unknown Since Add and Update use the same |
| Unknown error |