Customers

Post customer information

Create a single customer.

POST /orgs/{org_id}/customers

Parameters

Name	In	Type	Required	Description
org_id	path	string	true	organization name
body	body	any	true	‘none’

Request body - JsonObject

1

{}

None

Request example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48



curl -X POST https://customers.sta.masstack.com/v4/orgs/telco/customers \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "x-auth-roles: API_KEY" \
 --data-raw "{
  'type': 'PRIVATE_CUSTOMER',
  'preferred_language': 'es',
  'segment': 'CONSUMER',
  'contact_info': {
    'phone_numbers': [
      {
        'country_code': '+34',
        'number': '615667898',
        'type': 'MOBILE',
        'is_default': true
      }
    ],
    'emails': [
      {
        'email': 'email@example.com',
        'is_default': true
      }
    ],
    'postal_address': {
      'address_lines': [
        'Calle Mayor 2, 3º A'
      ],
      'postal_code': '28039',
      'locality': 'Fuenlabrada',
      'administrative_area': 'Madrid',
      'region_code': 'ES'
    }
  },
  'personal_info': {
    'identity_document': {
      'number': '14861628V',
      'type': 'NIF'
    },
    'name': 'Antonio',
    'first_surname': 'Benavente',
    'second_surname': 'Blanco',
    'gender': 'MALE',
    'nationality': 'ES',
    'birthdate': '2022-01-01'
  }
}" 

Responses

Code	Meaning	Description	Schema
201	Created	successful operation	CustomerCreated
400	Bad Request	Invalid request body	ErrorResponse
401	Unauthorized	Unauthorized	ErrorResponse
403	Forbidden	Forbidden resource	ErrorResponse
404	Not Found	Resource not found	ErrorResponse
405	Method Not Allowed	Method not allowed	None
409	Conflict	Conflict	ErrorResponse
500	Internal Server Error	Internal server error	ErrorResponse
503	Service Unavailable	Service unavailable	ErrorResponse
504	Gateway Time-out	Repository timeout	ErrorResponse

Get customer ids associated to a given identity document or email. When searching by identity document, the type of document must be provided.

Returns customer ids

GET /orgs/{org_id}/customers/search

Parameters

Name	In	Type	Required	Description
org_id	path	string	true	organization name
identity_document	query	string	false	Document with numbers and letters
identity_document_type	query	string	false	Document type
email	query	string	false	Email used by customer to authenticate

Enumerated Values

Property	Values
identity_document_type	one of [NIF, NIE, PASSPORT, CIF]

Request example

1
2
3
4
5



curl -X GET https://customers.sta.masstack.com/v4/orgs/telco/customers/search?identity_document='12345678A'&identity_document_type='NIF'&email='email@example.com' \
  -H "Accept: application/json" \
  -H "x-auth-roles: API_KEY"

Responses

Code	Meaning	Description	Schema
200	OK	successful operation	CustomerSearchResponse
400	Bad Request	Invalid request body	ErrorResponse
401	Unauthorized	Unauthorized	ErrorResponse
403	Forbidden	Forbidden resource	ErrorResponse
404	Not Found	Resource not found	ErrorResponse
500	Internal Server Error	Internal server error	ErrorResponse
503	Service Unavailable	Service unavailable	ErrorResponse
504	Gateway Time-out	Repository timeout	ErrorResponse

Get customer information

Returns all the info about a single customer given by customer id.

GET /orgs/{org_id}/customers/{customer_id}

Parameters

Name	In	Type	Required	Description
org_id	path	string	true	organization name
customer_id	path	string(uuid)	true	Customer identifier

Request example

1
2
3
4
5



curl -X GET https://customers.sta.masstack.com/v4/orgs/telco/customers/123e4567-e89b-12d3-a456-556642440000 \
  -H "Accept: application/json" \
  -H "x-auth-roles: API_KEY"

Responses

Code	Meaning	Description	Schema
200	OK	successful operation	CustomerResponse
400	Bad Request	Invalid request body	ErrorResponse
401	Unauthorized	Unauthorized	ErrorResponse
403	Forbidden	Forbidden resource	ErrorResponse
404	Not Found	Resource not found	ErrorResponse
405	Method Not Allowed	Method not allowed	None
500	Internal Server Error	Internal server error	ErrorResponse
503	Service Unavailable	Service unavailable	ErrorResponse
504	Gateway Time-out	Repository timeout	ErrorResponse

Delete customer information

Delete customer by its id.

DELETE /orgs/{org_id}/customers/{customer_id}

Parameters

Name	In	Type	Required	Description
org_id	path	string	true	organization name
customer_id	path	string(uuid)	true	Customer identifier

Request example

1
2
3
4
5



curl -X DELETE https://customers.sta.masstack.com/v4/orgs/telco/customers/123e4567-e89b-12d3-a456-556642440000 \
  -H "Accept: application/json" \
  -H "x-auth-roles: API_KEY"

Responses

Code	Meaning	Description	Schema
204	No Content	successful operation	None
400	Bad Request	Invalid request body	ErrorResponse
401	Unauthorized	Unauthorized	ErrorResponse
403	Forbidden	Forbidden resource	ErrorResponse
404	Not Found	Resource not found	ErrorResponse
409	Conflict	Conflict	ErrorResponse
500	Internal Server Error	Internal server error	ErrorResponse
503	Service Unavailable	Service unavailable	ErrorResponse
504	Gateway Time-out	Repository timeout	ErrorResponse

Update customer information

PATCH /orgs/{org_id}/customers/{customer_id}

Parameters

Name	In	Type	Required	Description
org_id	path	string	true	organization name
customer_id	path	string(uuid)	true	Customer identifier
body	body	PatchCustomerRequest	true	‘none’

Request body - JsonObject

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


{
  "preferred_language": "es",
  "contact_info": {
    "phone_numbers": [
      {
        "country_code": "+34",
        "number": "615667898",
        "type": "MOBILE"
      }
    ],
    "emails": [
      {
        "email": "email@example.com"
      }
    ]
  },
  "personal_info": {
    "name": "Antonio",
    "first_surname": "Benavente",
    "second_surname": "Blanco",
    "birthdate": "2022-01-01",
    "nationality": "ES"
  }
}

Name	Type	Required	Description
anonymous	object	false	Information required to update a customer
» preferred_language	LanguageCode	false	Customer’s preferred language code in ISO-639-1 lowercase format
» contact_info	PatchContactInfo	false	none

Name	Type	Required	Description
anonymous	any	false	none

Name	Type	Required	Description
» anonymous	object	false	none
»» personal_info	PatchPersonalInfo	false	Private customer personal information

Name	Type	Required	Description
» anonymous	object	false	none
»» company_info	PatchCompanyInfo	false	Update Company Info for a corporate customer. Only `legal_name` and `founding_date` are patchable. > Note: The `associated_users` field has been removed from this schema as of v4.57.0. > If sent alongside valid fields (`legal_name` or `founding_date`), it will be silently ignored > and the request will succeed with `204 No Content`. > If sent as the only field in `company_info`, the request will return `400 Bad Request` > with `"At least one field must be present"`. Valid usage: `json<br>{ "company_info": { "legal_name": "IBM", "founding_date": "1990-01-01" } }<br>` Invalid usage (deprecated, do not use): `json<br>{ "company_info": { "associated_users": [{ "identity_document": { "number": "12345678Z", "type": "NIF" } }] } }<br>`

Name	Type	Required	Description
» anonymous	object	false	none
»» digital_personal_info	PatchDigitalPersonalInfo	false	Update Digital Personal Info

Request example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30



curl -X PATCH https://customers.sta.masstack.com/v4/orgs/telco/customers/123e4567-e89b-12d3-a456-556642440000 \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "x-auth-roles: API_KEY" \
 --data-raw "{
  'preferred_language': 'es',
  'contact_info': {
    'phone_numbers': [
      {
        'country_code': '+34',
        'number': '615667898',
        'type': 'MOBILE'
      }
    ],
    'emails': [
      {
        'email': 'email@example.com'
      }
    ]
  },
  'personal_info': {
    'name': 'Antonio',
    'first_surname': 'Benavente',
    'second_surname': 'Blanco',
    'birthdate': '2022-01-01',
    'nationality': 'ES'
  }
}" 

Responses

Code	Meaning	Description	Schema
204	No Content	successful operation	None
400	Bad Request	Invalid request body	ErrorResponse
401	Unauthorized	Unauthorized	ErrorResponse
403	Forbidden	Forbidden resource	ErrorResponse
404	Not Found	Resource not found	ErrorResponse
409	Conflict	Conflict	ErrorResponse
500	Internal Server Error	Internal server error	ErrorResponse
503	Service Unavailable	Service unavailable	ErrorResponse
504	Gateway Time-out	Repository timeout	ErrorResponse

Set customer authorized representative

Creates or updates the authorized representative of a business customer. The `associated_users` array must contain exactly one element. Currently, only the `AUTHORIZED_REPRESENTATIVE` role is supported. If `role` is not provided, it defaults to `AUTHORIZED_REPRESENTATIVE`.

PUT /orgs/{org_id}/customers/{customer_id}/associated_users

Parameters

Name	In	Type	Required	Description
org_id	path	string	true	organization name
customer_id	path	string(uuid)	true	Customer identifier
body	body	PutAssociatedUsersRequest	true	‘none’

Request body - instance of PutAssociatedUsersRequest

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


{
  "associated_users": [
    {
      "identity_document": {
        "number": "14861628V",
        "type": "NIF"
      },
      "role": "AUTHORIZED_REPRESENTATIVE",
      "name": "Antonio",
      "first_surname": "Benavente",
      "second_surname": "Blanco",
      "nationality": "ES"
    }
  ]
}

Name	Type	Required	Description
associated_users	[AssociatedUser]	true	List of associated users to set. Currently only one representative per customer is supported.

Request example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21



curl -X PUT https://customers.sta.masstack.com/v4/orgs/telco/customers/123e4567-e89b-12d3-a456-556642440000/associated_users \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "x-auth-roles: API_KEY" \
 --data-raw "{
  'associated_users': [
    {
      'identity_document': {
        'number': '14861628V',
        'type': 'NIF'
      },
      'role': 'AUTHORIZED_REPRESENTATIVE',
      'name': 'Antonio',
      'first_surname': 'Benavente',
      'second_surname': 'Blanco',
      'nationality': 'ES'
    }
  ]
}" 

Responses

Code	Meaning	Description	Schema
204	No Content	Authorized representative set successfully	None
400	Bad Request	Invalid request body	ErrorResponse
401	Unauthorized	Unauthorized	ErrorResponse
403	Forbidden	Forbidden resource	ErrorResponse
404	Not Found	Resource not found	ErrorResponse
500	Internal Server Error	Internal server error	ErrorResponse
503	Service Unavailable	Service unavailable	ErrorResponse
504	Gateway Time-out	Repository timeout	ErrorResponse

Get customer tokenized credit cards

Returns all tokenized credit cards for the specified customer id

GET /orgs/{org_id}/customers/{customer_id}/available-credit-cards

Parameters

Name	In	Type	Required	Description
org_id	path	string	true	organization name
customer_id	path	string(uuid)	true	Customer identifier

Request example

1
2
3
4
5



curl -X GET https://customers.sta.masstack.com/v4/orgs/telco/customers/123e4567-e89b-12d3-a456-556642440000/available-credit-cards \
  -H "Accept: application/json" \
  -H "x-auth-roles: API_KEY"

Responses

Code	Meaning	Description	Schema
200	OK	Credit cards returned successfully	CustomerTokenizedCreditCards

Convert NIE to NIF

Updates a customer’s document from the specified NIE to the specified NIF

PATCH /orgs/{org_id}/customers/{customer_id}/convert-nie-to-nif

Parameters

Name	In	Type	Required	Description
org_id	path	string	true	organization name
customer_id	path	string(uuid)	true	Customer identifier
body	body	ConvertNieToNifRequest	true	‘none’

Request body - instance of ConvertNieToNifRequest

1
2
3


{
  "nif": "07687697Q"
}

Name	Type	Required	Description
nif	string	true	NIF

Request example

1
2
3
4
5
6
7
8
9



curl -X PATCH https://customers.sta.masstack.com/v4/orgs/telco/customers/123e4567-e89b-12d3-a456-556642440000/convert-nie-to-nif \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "x-auth-roles: API_KEY" \
 --data-raw "{
  'nif': '07687697Q'
}" 

Responses

Code	Meaning	Description	Schema
204	No Content	NIE converted successfully	None
400	Bad Request	Invalid request body	ErrorResponse
401	Unauthorized	Unauthorized	ErrorResponse
403	Forbidden	Forbidden resource	ErrorResponse
404	Not Found	Resource not found	ErrorResponse
409	Conflict	Conflict	ErrorResponse
500	Internal Server Error	Internal server error	ErrorResponse
503	Service Unavailable	Service unavailable	ErrorResponse
504	Gateway Time-out	Repository timeout	ErrorResponse