# Claims \[POST]

The `POST` request to the `/parties/{partyId}/claims` endpoint can be used to create a new claim for a party in the Participant Registry.

{% hint style="info" %}
The `POST` request to the `/parties/{partyId}/claims` is an **OPTIONAL** endpoint.
{% endhint %}

## Create new claim for a party

> Used to create a new claim for a participant.

```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":{"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"}}}]},"claimsResponse":{"title":"ClaimsResponse","type":"object","properties":{"claimsToken":{"type":"string","format":"application/jwt"}}}}},"paths":{"/parties/{partyId}/claims":{"post":{"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/claim"}}},"required":true},"tags":["Participant Registry (Optional)"],"parameters":[{"style":"simple","name":"partyId","description":"The id of the party for who a claim must be added. Can be anyone of  the party id from id or alsoKnownAs attributes of that participant. Since all participants are automatically allocated the derived  ishare did, that id is always an option to search for a participant.","schema":{"type":"string"},"in":"path","required":true}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/claimsResponse"}}},"description":"OK"}},"deprecated":false,"operationId":"register-new-claim","summary":"Create new claim for a party","description":"Used to create a new claim for a participant."}}}}
```

### Request model

The following URL parameter must be used.

* `partyId` {url}/parties/{**partyId**} <mark style="color:red;">(Required)</mark>\
  **String**. The id of the party for who a new claim must be registered. Can be anyone of the party id from id or alsoKnownAs attributes of that participant. Since all participants are automatically allocated the derived ishare did, that id is always an option to search for a participant.

The request must be passed as JWT. The JSON body must contain a claim. 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.

### Example request

```json
POST /parties/ HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json

{
  "id": "5ffb4bb9-2020-4045-a922-3bd84e78f709",
  "registrarId": " did:ishare:NTRNL-10000000",
  "type": "frameworkCompliance",
  "frameworkId": "iSHARE",
  "status": "active",
  "startDate": "2025-01-01T00:00:00.000Z",
  "endDate": "2026-12-31T00:00:00.000Z",
  "additionalInfo": {
    "description": "Example description",
    "publiclyPublishable": true,
    "website": "https://www.example.com"
  }
}
```

### Response model

The response will be equal to the response of the [GET request for retrieving a single claim](https://dev.ishare.eu/participant-registry-role/claims-single-claim-get). Refer to the response model as defined here.

### Example response

Refer to the example response under the [GET request](https://dev.ishare.eu/participant-registry-role/claims-single-claim-get) definition.