Users

Creating a new User

A new user can be created with:

curl --location --request POST '{{api_url}}/users' \
--header 'Authorization: {{jwt_token}}' \
--header 'interaction-id: {{interactionId}}' \
--header 'Content-Type: application/json' \
--data-raw '{{body}}'

where

Variable	Description
`{{api_url}}`	Endpoint of the api. (Staging) (Production)
`{{jwt_token}}`	The JWT-token, which has been generated by authentication.
`{{interactionId}}`	Unique Identifier of the cash machine (or virtual equivalent, e.g. online-shop), which produced the receipt. This ID has to be listed in the Convercus System as with this ID, the connection to the call origin is made.
`{{body}}`	Body with user data parameters, specified in the following.

The body may look like this:

{
"emailAddress": "[email protected]",
"givenName": "testName",
"familyName": "testFamilyname",
"streetHouseNo": "testStreet",
"zipCode": "12345",
"city": "testCity",
"countryCode": "DE",
"genderCode": "FEMALE",
"birthDate": "1991-01-01",
"phone": "012345",
"customProperties": [
{
"id": "9f7e8b6d-d029-4ae2-86b7-2f551b96c5bc",  
"name": "exampleCustomProperty 1",
"value": "abcde"
},
{
"id": "fc669654-5e06-42a7-a126-5ab1434debdb",
"name": "exampleCustomProperty 1",
"value": "10001"
}
]
}

with (all string-type)

Attribute	Description	Relevance
emailAddress	E-Mail of customer	Mandatory
givenName	First name of customer	Optional
familyName	Family name of customer	Optional
streetHouseNo	Adress of customer	Optional
zipCode	Zip-Code of customer	Optional
city	City of residence	Optional
countryCode	Country of residence, with code specified in “ISO 3166-1 alpha-2”	Optional
genderCode	Gender, can be one of: MALE FEMALE DIVERSE	Optional
birthDate	Date of birth in format YYYY-MM-DD: e.g. "1991-01-01"	Optional
phone	Phone number of customer	Optional
customProperties	array with additional properties in pairs of id: UUID, name: string, value: string, that have been preconfigured.	Optional

The user will be created in the database and is assigned a userId, which can be obtained from the response’s header section Location:

Location	`{{api_url}}`/users/userId

Displaying User properties

The user’s properties can be retrieved with the unique userId a user is assigned with at creation. This userId may also be extracted from a membership.

curl --location --request GET '{{api_url}}/users/{{userId}}/' \
--header 'Authorization: {{jwt_token}}' \
--header 'interaction-id: {{interactionId}}' \
--header 'Content-Type: application/json' \

with

Variable	Description
`{{api_url}}`	Endpoint of the api. (Staging) (Production)
`{{userId}}`	The unique identification a user was assigned at creation. Alternatively, this is taken from a membership-connection.
`{{jwt_token}}`	The JWT-token, which has been generated by authentication.
`{{interactionId}}`	Unique Identifier of the cash machine (or virtual equivalent, e.g. online-shop), which produced the receipt. This ID has to be listed in the Convercus System as with this ID, the connection to the call origin is made.

This will retrieve all properties the user has, e.g.

{
"userId": "dd820ab2-6833-4ee3-9add-7bebf4dadddd",
"emailAddress": "[email protected]",
"givenName": "testName",
"familyName": "testFamilyname",
"streetHouseNo": "testStreet",
"zipCode": "12345",
"city": "testCity",
"countryCode": "DE",
"genderCode": "FEMALE",
"birthDate": "1991-01-01",
"phone": "012345",
"customProperties": [
{
"name": "exampleCustomProperty 1",
"value": "abcde"
}
]
}

again with

Attribute	Description	Relevance
emailAddress	E-Mail of customer	Mandatory
givenName	First name of customer	Optional
familyName	Family name of customer	Optional
streetHouseNo	Address of customer	Optional
zipCode	Zip-Code of customer	Optional
city	City of residence	Optional
countryCode	Country of residence, with code specified in “ISO 3166-1 alpha-2”	Optional
genderCode	Gender, can be one of: MALE FEMALE DIVERSE	Optional
birthDate	Date of birth in format YYYY-MM-DD: e.g. "1991-01-01"	Optional
phone	Phone number of customer	Optional
customProperties	array with additional properties in pairs of name: string, value: string, that have been preconfigured.	Optional

Note, that the content of this response may differ with the program. There may be multiple customProperties, which are completely program-specific. Furthermore, it is possible that in future versions, the response will be expanded by more fields, so you should make sure to be able to accept more output.

Updating User Information

Using a users unique userId, a user can be updated in two variants:

Overwrite all User Data (PUT)

A PUT request will update the user data given in the argument, deleting all pre-existing properties that were not specified in the request.

curl --location --request PUT '{{api_url}}/users/{{userId}}' \
--header 'Authorization: {{jwt_token}}' \
--header 'interaction-id: {{interactionId}}' \
--header 'Content-Type: application/json' \
--data-raw '{{body}}'

with

Variable	Description
`{{api_url}}`	Endpoint of the api. (Staging) (Production)
`{{userId}}`	The unique identification a user was assigned at creation.
`{{jwt_token}}`	The JWT-token, which has been generated by authentication.
`{{interactionId}}`	Unique Identifier of the cash machine (or virtual equivalent, e.g. online-shop), which produced the receipt. This ID has to be listed in the Convercus System as with this ID, the connection to the call origin is made.
`{{body}}`	Body with user data parameters, specified in the following.

The body may look like this:

{
"emailAddress": "[email protected]",
"givenName": "testName",
"familyName": "testFamilyname",
"streetHouseNo": "testStreet",
"zipCode": "22222",
"city": "testCity",
"countryCode": "DE",
"genderCode": "FEMALE",
"birthDate": "1991-01-01",
"phone": "999999999",
"customProperties": [
{
"name": "exampleCustomProperty 1",
"value": "abcde"
}
]
}

with

Attribute	Description	Relevance
emailAddress	E-Mail of customer	Mandatory
givenName	First name of customer	Optional
familyName	Family name of customer	Optional
streetHouseNo	Address of customer	Optional
zipCode	Zip-Code of customer	Optional
city	City of residence	Optional
countryCode	Country of residence, with code specified in “ISO 3166-1 alpha-2”	Optional
genderCode	Gender, can be one of: MALE FEMALE DIVERSE	Optional
birthDate	Date of birth in format YYYY-MM-DD: e.g. "1991-01-01"	Optional
phone	Phone number of customer	Optional
customProperties	array with additional properties in pairs of name: string, value: string, that have been preconfigured.	Optional

As mentioned before, this will delete all properties, that are not specified in the request.

Overwrite selected User Data (PATCH)

Contrary, a PATCH request will change all properties given in the argument, while leaving all arguments not specified in the request unmodified.

curl --location --request PATCH '{{api_url}}/users/{{userId}}' \
--header 'Authorization: {{jwt_token}}' \
--header 'interaction-id: {{interactionId}}' \
--header 'Content-Type: application/json' \
--data-raw '{{body}}'

with

Variable	Description
`{{api_url}}`	Endpoint of the api. (Staging) (Production)
`{{userId}}`	The unique identification a user was assigned at creation.
`{{jwt_token}}`	The JWT-token, which has been generated by authentication.
`{{interactionId}}`	Unique Identifier of the cash machine (or virtual equivalent, e.g. online-shop), which produced the receipt. This ID has to be listed in the Convercus System as with this ID, the connection to the call origin is made.
`{{body}}`	Body with user data parameters, specified in the following.

The body with parameters may look like this:

{
"zipCode": 22222
}

with the same possible parameters as the PUT request:

Attribute	Description	Relevance
emailAddress	E-Mail of customer	Optional
givenName	First name of customer	Optional
familyName	Family name of customer	Optional
streetHouseNo	Address of customer	Optional
zipCode	Zip-Code of customer	Optional
city	City of residence	Optional
countryCode	Country of residence, with code specified in “ISO 3166-1 alpha-2”	Optional
genderCode	Gender, can be one of: MALE FEMALE DIVERSE	Optional
birthDate	Date of birth in format YYYY-MM-DD: e.g. "1991-01-01"	Optional
phone	Phone number of customer	Optional
customProperties	array with additional properties in pairs of name: string, value: string, that have been preconfigured. Note: customProperties always requires all properties, even if only one or a few need to be changed. All properties that are not specified, even if they remain unchanged, will be deleted.	Optional

The examplary request will update the specified properties in the data-raw argument, in this case the zipCode.

Individual properties can be deleted by updating them with null, e.g.:

curl --location --request PATCH '{{api_url}}/users/{{userId}}' \
--header 'Authorization: {{jwt_token}}' \
--header 'interaction-id: {{interactionId}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"zipCode": null
}'

Note: When updating the custom properties array, each entry has to be sent with the request, as both PUT and PATCH can only update the array in its entirety.

Deleting Users

A user can be deleted from the database, by sending a DELETE request with the unique userId.

curl --location --request DELETE '{{api_url}}/users/{{userId}}' \
--header 'Authorization: {{jwt_token}}' \
--header 'interaction-id: {{interactionId}}' \
--header 'Content-Type: application/json' \

again with

Variable	Description
`{{api_url}}`	Endpoint of the api. (Staging) (Production)
`{{userId}}`	The unique identification a user was assigned at creation.
`{{jwt_token}}`	The JWT-token, which has been generated by authentication.
`{{interactionId}}`	Unique Identifier of the cash machine (or virtual equivalent, e.g. online-shop), which produced the receipt. This ID has to be listed in the Convercus System as with this ID, the connection to the call origin is made.

This will delete the user and anonymize the user data while simultaniously resetting the loyalty points to 0.