# Parties \[POST]
The `POST` request to the `/parties` endpoint can be used to create a new party in the Participant Registry.
{% hint style="info" %}
The `POST` request to the `/parties` is an **OPTIONAL** endpoint. For more information on **OPTIONAL** specifications, see [functional requirements per role.](https://framework.ishare.eu/detailed-descriptions/functional/functional-requirements-per-role)
{% endhint %}
## Create new party
> Used to programmatically create a participant. To create a party as part of the iSHARE Framework, at minimum the following claims MUST be provided: - x509Certificate or idpAssertion - frameworkCompliance - frameworkAgreement - frameworkRole. For all roles except for Service Consumer and Entitled Party an x509Certificate claim is required. Service Consumer and Entitled Party MUST either provide a x509Certificate claim or idpAssertion claim if authenticating via Identity Provider.
```json
{"openapi":"3.0.0","info":{"title":"iSHARE API specifications","version":"3.0"},"tags":[{"name":"Participant Registry (Optional)","description":"Optional endpoints for the iSHARE Participant Registry API."}],"servers":[{"description":"iSHARE test network base domain","url":"https://isharetest.net"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"OAuth 2.0 authorization based on bearer token. MUST contain “Bearer “ + access token value. Must be provided if restricted endpoints are needed."}},"schemas":{"party":{"title":"Party","required":["id","name","claims"],"type":"object","properties":{"id":{"description":"Primary identifier (did:ishare) of the party.","type":"string"},"name":{"description":"Name of the party.","type":"string"},"alsoKnownAs":{"description":"Array of registered party ids of the party with which the party is also identified. Optional, because a party could be identified with only its did:ishare (in the 'id' property).","type":"array","items":{"type":"string"}},"claims":{"type":"array","description":"Array of registered claims for the party","items":{"$ref":"#/components/schemas/claim"}}}},"claim":{"discriminator":{"propertyName":"type","mapping":{"frameworkCompliance":"#/components/schemas/claimFrameworkCompliance","authRegistry":"#/components/schemas/claimAuthRegistry","frameworkAgreement":"#/components/schemas/claimFrameworkAgreement","frameworkRole":"#/components/schemas/claimFrameworkRole","dataspaceMembership":"#/components/schemas/claimDataspaceMembership","dataspaceAgreement":"#/components/schemas/claimDataspaceAgreement","dataspaceRole":"#/components/schemas/claimDataspaceRole","x509Certificate":"#/components/schemas/claimX509Certificate","idpAssertion":"#/components/schemas/claimIdpAssertion"}},"oneOf":[{"$ref":"#/components/schemas/claimFrameworkCompliance"},{"$ref":"#/components/schemas/claimAuthRegistry"},{"$ref":"#/components/schemas/claimFrameworkAgreement"},{"$ref":"#/components/schemas/claimFrameworkRole"},{"$ref":"#/components/schemas/claimDataspaceMembership"},{"$ref":"#/components/schemas/claimDataspaceAgreement"},{"$ref":"#/components/schemas/claimDataspaceRole"},{"$ref":"#/components/schemas/claimX509Certificate"},{"$ref":"#/components/schemas/claimIdpAssertion"}]},"claimFrameworkCompliance":{"allOf":[{"$ref":"#/components/schemas/claimSkeleton"},{"type":"object","title":"frameworkComplianceClaim","description":"Participant claim that holds framework compliance","required":["frameworkId","status","startDate","endDate"],"properties":{"type":{"type":"string","enum":["frameworkCompliance"]},"frameworkId":{"type":"string","description":"ID of the framework the compliance is claimed for"},"capabilityUrl":{"type":"string","description":"Capabilities endpoint of the party in the framework. Required base on the role of the party in the framework (in iSHARE Framework required for Service Provider, Identity Provider, Participant Registry and Authorisation Registry).","format":"uri"},"additionalInfo":{"allOf":[{"$ref":"#/components/schemas/additionalInfo"}]}}}]},"claimSkeleton":{"type":"object","required":["id","registrarId","type","status"],"properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the claim, must be a UUID"},"status":{"type":"string","description":"The status of a claim concerns the status of that what the claim contains. For example: the status \"active\" for frameworkCompliance means that the party currently complies to the framework. Statusses are defined as follows:\n- active: The claim is currently valid (every claim that should be used \n (trusted) mus have this status)\n- inactive: The claim is not yet valid or is expired - revoked: The claim has been revoked permanently - suspended: The claim is suspended temporarily","enum":["active","inactive","revoked","suspended"]},"registrarId":{"type":"string","description":"Identifier of the party who registered the claim. This can be any of the Party ID from id or alsoKnownAs attributes of that participant."},"startDate":{"type":"string","description":"UTC timestamp (RFC3339, ISO8601) of the start date of the claim validity","format":"date-time"},"endDate":{"type":"string","description":"UTC timestamp (RFC3339, ISO8601) of the end date of the claim validity","format":"date-time"}}},"additionalInfo":{"title":"AdditionalInfo","description":"Object which contains additional general contact information of the party.","required":["publiclyPublishable"],"type":"object","properties":{"description":{"description":"A brief description of the party","type":"string"},"logo":{"description":"URL pointing to the endpoint where company logo can be found.","type":"string"},"website":{"description":"Website address of the party","type":"string"},"companyPhone":{"description":"General company phone number of the party","type":"string"},"companyEmail":{"description":"General company email id of the party","type":"string"},"publiclyPublishable":{"description":"Consent to publicly publish the information contained in this object","type":"boolean"},"countriesOfOperation":{"description":"An array of ISO names of the countries where the party operates","type":"array","items":{"type":"string"}},"sectorIndustry":{"description":"An array of GICS based sectors/industry that party serves in","type":"array","items":{"type":"string"}},"tags":{"description":"An free text field containing keywords relevant for party","type":"string"}}},"claimAuthRegistry":{"allOf":[{"$ref":"#/components/schemas/claimSkeleton"},{"$ref":"#/components/schemas/authRegistry"},{"type":"object","title":"authRegistryClaim","description":"Presents the selected Authorisation Registry (AR) to be used for the party. An AR can be selected for use in a dataspace (then provide the dataspaceId) or for use in a framework (then provide the frameworkId), or for use with a specific Service Provider (then provide the serviceProviderPartyId), or a combination of these. If none is provided, the AR must be considered as the default AR for the party.","properties":{"type":{"type":"string","enum":["authRegistry"]},"dataspaceId":{"description":"Optional ID of the dataspace","type":"string"},"frameworkId":{"description":"Optional ID of the framework","type":"string"},"serviceProviderPartyId":{"description":"Optional party id of the Service Provider for which this AR is selected by the Entitled Party.","type":"string"}}}]},"authRegistry":{"title":"authRegistry","description":"Object which contains details about the authorisation registers that the party uses.","required":["name","id","authUrl","authRegistryId"],"type":"object","properties":{"name":{"description":"The name of the authorisation registry provider","type":"string"},"authRegistryId":{"description":"The Id of the authorisation registry provider","type":"string"},"authUrl":{"description":"The URL pointer specific to the party where authorisations can be queried/checked from","type":"string"},"dataspaceId":{"description":"The id of the data space where the party uses this authorisation registry provider","type":"string"},"dataspaceName":{"description":"The name of the data space corresponding to the data space id","type":"string","readOnly":true},"serviceProviderPartyId":{"description":"Optional party id of the Service Provider for which this AR is selected by the Entitled Party.","type":"string"},"serviceIdentifier":{"description":"Optional identifier of the Service (Capability) of the Service Provider for which this AR is selected by the Entitled Party (#/components/schemas/Service/identifier).","type":"string"}}},"claimFrameworkAgreement":{"allOf":[{"$ref":"#/components/schemas/claimSkeleton"},{"$ref":"#/components/schemas/agreement"},{"type":"object","title":"frameworkAgreementClaim","description":"Required. Claims for Accession Agreement and Terms of Use are required at minimum, may have additional agreements.","required":["frameworkId"],"properties":{"type":{"type":"string","enum":["frameworkAgreement"]},"frameworkId":{"description":"ID of the framework","type":"string"}}}]},"agreement":{"title":"Agreement","description":"Object which contains details about contracts including dataspace contracts that party has agreed and signed to.","required":["agreementType","agreementId","title","status"],"type":"object","properties":{"agreementType":{"description":"Descriptive type of the agreement. Framework or dataspace may define agreement types.","type":"string"},"agreementId":{"description":"ID that refers to the agreement.","type":"string"},"title":{"description":"The name of the agreement or agreement file","type":"string"},"verificationHash":{"description":"The calculated hash of the agreement file that has been uploaded. Note agreements are not stored in the ledger, but only their hash. The verificationHash must be calculated using the SHA256 hashing algorithm.","type":"string"}}},"claimFrameworkRole":{"allOf":[{"$ref":"#/components/schemas/claimSkeleton"},{"$ref":"#/components/schemas/role"},{"type":"object","title":"frameworkRoleClaim","description":"Required if defined by dataspace. When a dataspace defines its own roles for participants, it can be added through this claim.","required":["frameworkId"],"properties":{"type":{"type":"string","enum":["frameworkRole"]},"frameworkId":{"description":"ID of the framework","type":"string"}}}]},"role":{"title":"Role","description":"Object which contains details about the role of the party. The details include the level of assurance as well as compliance status.","required":["roleId","status","startDate","endDate","loa","compliancyVerified","legalAdherence"],"type":"object","properties":{"roleId":{"description":"Name of the role as defined by the framework or dataspace.","type":"string"},"title":{"description":"Title of the role.","type":"string"},"loa":{"description":"Party's level of assurance. Available values are low, substantial and high.","type":"string","enum":["low","substantial","high","not-applicable"]},"compliancyVerified":{"description":"Compliance requirements of this role has been met by party. Possible values are yes, no and not-applicable","type":"string","enum":["yes","no","not-applicable"]},"legalAdherence":{"description":"Legal requirements of this role has been met by party including signing of appropriate agreements","type":"string","enum":["yes","no","not-applicable"]}}},"claimDataspaceMembership":{"allOf":[{"$ref":"#/components/schemas/claimSkeleton"},{"type":"object","title":"dataspaceMembershipClaim","description":"Participant claim that holds dataspace membership","required":["dataspaceId","startDate","endDate","legalAdherence"],"properties":{"type":{"type":"string","enum":["dataspaceMembership"]},"dataspaceId":{"type":"string","description":"Identifier of the dataspace of which the participant is a member of"},"capabilityUrl":{"type":"string","description":"Capabilities endpoint of the party in the dataspace May be required based on the role of the party in the dataspace.","format":"uri"},"legalAdherence":{"type":"string","description":"Whether legal adherence is required, not required or not applicable","enum":["yes","no","not-applicable"]},"additionalInfo":{"allOf":[{"$ref":"#/components/schemas/additionalInfo"}]}}}]},"claimDataspaceAgreement":{"allOf":[{"$ref":"#/components/schemas/claimSkeleton"},{"$ref":"#/components/schemas/agreement"},{"type":"object","title":"dataspaceAgreementClaim","description":"Required if defined by dataspace. When a dataspace defines its own agreement for participants, it can be added through this claim.","required":["dataspaceId"],"properties":{"type":{"type":"string","enum":["dataspaceAgreement"]},"dataspaceId":{"description":"ID of the dataspace","type":"string"}}}]},"claimDataspaceRole":{"allOf":[{"$ref":"#/components/schemas/claimSkeleton"},{"$ref":"#/components/schemas/role"},{"type":"object","title":"dataspaceRoleClaim","description":"Required if defined by dataspace. When dataspace adefines its own roles for participants, it can be added through this claim.","required":["dataspaceId"],"properties":{"type":{"type":"string","enum":["dataspaceRole"]},"dataspaceId":{"description":"ID of the dataspace","type":"string"}}}]},"claimX509Certificate":{"allOf":[{"$ref":"#/components/schemas/claimSkeleton"},{"type":"object","title":"x509CertificateClaim","description":"x509Certificate claim must be a valid certificate issued by a _certificate root_ from the trusted list. It is required for all roles except for Service Consumer that does not have machine to machine (M2M)interaction and Entitled Party. Service Consumer with no M2M interaction and Entitled Party may still choose to use an x509Certificate.","required":["subjectName","certificateType","x5c","x5t#s256","status"],"properties":{"type":{"type":"string","enum":["x509Certificate"]},"subjectName":{"description":"subjectName as encoded in the X.509 certificate which corresponds with the party that is being requested from the Participant Registry. Used by the Participant Registry to match the certificate identifier.","type":"string"},"certificateType":{"description":"type of certificate","type":"string"},"x5c":{"description":"The base64 encoded pem format value of the certificate identified by its subject name and fingerprint","type":"string"},"x5t#s256":{"description":"The SHA256 fingerprint of the certificate","type":"string"},"status":{"description":"Status of the certificate (active or revoked)","type":"string","enum":["active","revoked"]}}}]},"claimIdpAssertion":{"allOf":[{"$ref":"#/components/schemas/claimSkeleton"},{"type":"object","title":"idpAssertionClaim","description":"The idpAssertion is allowed only for the roles Entitled Party and Service Consumer without M2M interaction. It is required if those roles do not have a x509Certificate claim present. idpAssertion claim must be a valid assertion issued by a certified Identity Provider.","required":["assertion"],"properties":{"type":{"type":"string","enum":["idpAssertion"]},"assertion":{"description":"Value of the assertion","type":"string"}}}]},"partyResponse":{"title":"PartyResponse","type":"object","properties":{"partyToken":{"type":"string","format":"application/jwt"}}}}},"paths":{"/parties":{"post":{"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/party"}}},"required":true},"tags":["Participant Registry (Optional)"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/partyResponse"}}},"description":""}},"deprecated":false,"operationId":"register-new-party","summary":"Create new party","description":"Used to programmatically create a participant. To create a party as part of the iSHARE Framework, at minimum the following claims MUST be provided: - x509Certificate or idpAssertion - frameworkCompliance - frameworkAgreement - frameworkRole. For all roles except for Service Consumer and Entitled Party an x509Certificate claim is required. Service Consumer and Entitled Party MUST either provide a x509Certificate claim or idpAssertion claim if authenticating via Identity Provider."}}}}
```
### Request model
The request must be passed as JWT. The JSON model in the JWT is as follows.
* `id`\
**String**. (Required)\
Primary identifier (iSHARE-ID) of the party.
* `name`\
**String**. (Required)\
Name of the party.
* `alsoKnownAs`\
**Array of strings**.\
Array of registered party ids of the party with which the party is also identified. Optional, because a party could be identified with only its iSHARE-ID (in the 'id' property).
* `claims`\
**Array of objects**. (Required)\
Array of claims for the party. Refer to [claim-models](https://dev.ishare.eu/participant-registry-role/claim-models "mention") for an overview of available claims. In the `POST` request the `id` and `registrarId` fields may be omitted, as they will be provided by the Participant Registry. To create a party as part of the iSHARE Framework, at minimum the following claims MUST be provided:
* x509Certificate or idpAssertion
* frameworkCompliance
* frameworkAgreement
* frameworkRole
For all roles except for Service Consumer and Entitled Party an x509Certificate claim is required. Service Consumer and Entitled Party MUST either provide a x509Certificate claim or idpAssertion claim if authenticating via Identity Provider.
### Example request
```json
POST /parties HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
{
"id": "did:ishare:EU.NL.NTRNL-12345678",
"name": "Example Corporation",
"alsoKnownAs": [
"did:ishare:EU.NL.NTRNL-12345678",
"did:elsi:LEIXG-724500AZSGBRY55MNS59",
"did:web:example.com",
"CoC:123456789"
],
"claims": [
{
"status": "active",
"startDate": "2025-01-01T00:00:00.000Z",
"endDate": "2026-12-31T00:00:00.000Z",
"type": "frameworkCompliance",
"frameworkId": "iSHARE",
"additionalInfo": {
"description": "Example description",
"publiclyPublishable": true,
"website": "https://www.example.com"
}
},
{
"status": "active",
"startDate": "2025-01-01T00:00:00.000Z",
"endDate": "2026-12-31T00:00:00.000Z",
"type": "frameworkRole",
"roleId": "ServiceConsumer",
"title": "Service Consumer",
"loa": "not-applicable",
"compliancyVerified": "yes",
"legalAdherence": "yes",
"frameworkId": "iSHARE"
},
{
"status": "active",
"startDate": "2025-01-01T00:00:00.000Z",
"endDate": "2026-12-31T00:00:00.000Z",
"type": "frameworkAgreement",
"agreementType": "AccessionAgreement",
"agreementId": "fd06e213-7db2-469b-b9ce-de00e48e1817",
"title": "Accession Agreement",
"verificationHash": "aef5bb5e3ab49150a53b89628ab8593315b6686f3f96497277feb9d658527acb",
"frameworkId": "iSHARE"
},
{
"status": "active",
"startDate": "2025-01-01T00:00:00.000Z",
"endDate": "2026-12-31T00:00:00.000Z",
"type": "frameworkAgreement",
"agreementType": "TermsOfUse",
"agreementId": "3cde6ff3-243d-48c0-8003-31d3fea3c1f1",
"title": "Terms of Use",
"verificationHash": "f727a459b5ca5a32e5aff71c03fdaa697cd46a45eb04eecaaae5931eb9a5c00e",
"frameworkId": "iSHARE"
},
{
"status": "active",
"startDate": "2025-01-01T00:00:00.000Z",
"endDate": "2026-12-31T00:00:00.000Z",
"type": "x509Certificate",
"subjectName": "C=NL,O=Test Service Consumer,CN=Test Service Consumer,2.5.4.97=NTRNL-10000001",
"certificateType": "eSeal",
"x5c": "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",
"x5t#s256": "4670551451113b19425f8d63c3d6ce444b58de60831101748e9fb97b3e8766f8"
}
]
}
```
### Response model
The response will be equal to the response of the GET request for retrieving a single party. Please refer to the [response model as defined here](https://dev.ishare.eu/single-party#response-model).
### Example response
Please also refer to the [example response](https://dev.ishare.eu/single-party#example-response) under the GET request definition.