Skip to content

Latest commit

 

History

History
236 lines (196 loc) · 13.4 KB

api-person.md

File metadata and controls

236 lines (196 loc) · 13.4 KB
Raw

Census API: People

Qualified identifiers

ℹ️ A person qualified identifier is built joining its numeric identifier and the system name with an at sign (@). For example, a person could be identified with the qualified identifier 123@census, and also with 126@decidim. Also, an identifier by document ID could be used, in the form 1R@document_id. Census API always identify people using its qualified identifier to avoid mixing-up when working with numeric identifiers only.

Person registration

📍 Creates a registration procedure for a person.

POST api/v1/people
Parameter Data type Description Format
person_id string Person's qualified identifier
first_name string Person's first name
last_name1 string Person's first last name
last_name2 string Person's second last name
document_type string Person's document type dni, nie or passport
document_id string Person's document id
document_scope_code string Person's document scope code
born_at date Person's born date YYYY-MM-DD
gender string Person's gender male, female, other or undisclosed
address string Person's address
address_scope_code string Person's address_scope_code
postal_code string Person's postal_code
email string Person's email
scope_code string Person's scope_code
phone string Person's phone
  • All parameters are mandatory, except person_id.

Return value

  • When the person registration is successfully created, server response will be :accepted (HTTP 202) and the JSON will include the person_id key with the new person identifier.
  • When the given parameters for the person are invalid, server response will be :unprocessable_entity (HTTP 422) and a JSON with the errors for each parameter.
  • When there is an error creating the registration, server response will be :server_internal_error (HTTP 500).

Person data changes

📍 Creates a person data change procedure.

PATCH api/v1/people/:person_id
Parameter Data type Description Format
person_id string Person's qualified identifier
first_name string Person's first name
last_name1 string Person's first last name
last_name2 string Person's second last name
document_type string Person's document type dni, nie or passport
document_id string Person's document id
document_scope_code string Person's document scope code
born_at date Person's born date YYYY-MM-DD
gender string Person's gender male, female, other or undisclosed
address string Person's address
address_scope_code string Person's address_scope_code
postal_code string Person's postal_code
email string Person's email
scope_code string Person's scope_code
phone string Person's phone
  • All parameters are optional, except person_id.

Return value

  • When the person data change request is successfully created, server response will be :accepted (HTTP 202).
  • When the given parameters for the person are invalid, server response will be :unprocessable_entity (HTTP 422) and a JSON with the errors for each parameter.
  • When there is an error creating the person data change, server response will be :server_internal_error (HTTP 500).

Person cancellation

📍 Creates a cancellation procedure for a person.

DELETE api/v1/people/:person_id
Parameter Data type Description
person_id string Person's qualified identifier
channel string Application name used to perform the cancellation request
reason string Reason for the cancellation (optional)

Return value

  • When the person cancellation is successfully created, server response will be :accepted (HTTP 202).
  • When the given parameters for the procedure are invalid, server response will be :unprocessable_entity (HTTP 422) and a JSON with the errors for each parameter.
  • When there is an error creating the cancellation, server response will be :server_internal_error (HTTP 500).

Person retrieval

📍 Retrieve the person data. It also allows to retrieve the person's data as it was at a given timestamp.

GET api/v1/people/:person_id
Parameter Data type Description Format
person_id string Person's qualified identifier
with_scope boolean Include scopes information in the response (optional) true or false (by default)
version_at datetime Timestamp used to query person data (optional) YYYY-MM-DD HH:MM +HH:MM

Return value

  • When the person exists in the database, server response will be :ok (HTTP 200) with a JSON with all the person data: (fields id.
Parameter Data type Description Format
person_id string Person's qualified identifier
first_name string Person's first name
last_name1 string Person's first last name
last_name2 string Person's second last name
document_type string Person's document type dni, nie or passport
document_id string Person's document id
document_scope_code string Person's document scope code
born_at date Person's born date YYYY-MM-DD
gender string Person's gender male, female, other or undisclosed
address string Person's address
address_scope_code string Person's address_scope_code
postal_code string Person's postal_code
email string Person's email
scope_code string Person's scope_code
phone string Person's phone
state string Person's state pending, enabled, cancelled or trashed
membership_level string Person's membership level follower or member
verification string Person's identity verification not_verified, verification_requested, verification_received, verified, mistake or fraud
phone_verification string Person's phone verification not_verified, verified or reassigned
external_ids json Person's external systems ids
additional_information json Person's misc additional information
membership_allowed? boolean Is person is allowed to be member true or false
scopes json Person's scopes information (if requested) Array of scope objects (id, name, scope_type, code and mappings)
  • When there is no person for the given person_id, server response will be :not_found (HTTP 404) and an empty JSON.

Person set additional information

📍 Sets additional information for the person.

POST api/v1/people/:person_id/additional_informations

Parameter | Data type | Description | Format ----------------------|-----------|------------------------------------------------- person_id | string | Person's qualified identifier key | string | Additional information key json_value | string | Additional information value | Serialized JSON

Return value

  • When the information is successfully saved, server response will be :accepted (HTTP 202).
  • When the given parameters for the procedure are invalid, server response will be :unprocessable_entity (HTTP 422) and a JSON with the errors for each parameter.
  • When there is an error saving the information, server response will be :server_internal_error (HTTP 500).

Membership level change

📍 Creates a membership level change procedure for a person.

POST api/v1/people/:person_id/membership_levels
Parameter Data type Description Format
person_id string Person's qualified identifier
membership_level string Target level follower or member
  • All parameters are mandatory.

Return value

  • When the membership level change request is successfully created, server response will be :accepted (HTTP 202).
  • When the given parameters for the procedure are invalid, server response will be :unprocessable_entity (HTTP 422) and a JSON with the errors for each parameter.
  • When there is an error creating the membership level change, server response will be :server_internal_error (HTTP 500).

Document verification

📍 Creates a document verification procedure for a person.

POST api/v1/people/:person_id/document_verifications
Parameter Data type Description Format
person_id string Person's qualified identifier
files json A JSON with an array of hashes with three fields: filename, content_type and base_64_content.
prioritized boolean Prioritize the processing of this procedure (optional) true or false (by default)

Return value

  • When the document verification is successfully created, server response will be :accepted (HTTP 202).
  • When the given parameters for the procedure are invalid, server response will be :unprocessable_entity (HTTP 422) and a JSON with the errors for each parameter.
  • When there is an error creating the verification, server response will be :server_internal_error (HTTP 500).

Start a phone verification

📍 Starts a phone verification sending an SMS with the code to the person or given phone.

GET api/v1/people/:person_id/phone_verifications/new
Parameter Data type Description
person_id string Person's qualified identifier
phone string A different phone number to be verified (optional)

Return value

  • When the message is successfully sent, server response will be :accepted (HTTP 202).
  • When the given parameters for the procedure are invalid, server response will be :unprocessable_entity (HTTP 422) and a JSON with the errors for each parameter.
  • When there is an error sending the message, server response will be :server_internal_error (HTTP 500).

Phone verification

📍 Creates a phone verification procedure for a person.

POST api/v1/people/:person_id/phone_verifications
Parameter Data type Description
person_id string Person's qualified identifier
received_code string The validation code received in the phone
phone string A different phone number to be verified (optional)

Return value

  • When the phone verification is successfully created, server response will be :accepted (HTTP 202).
  • When the given parameters for the procedure are invalid, server response will be :unprocessable_entity (HTTP 422) and a JSON with the errors for each parameter.
  • When there is an error creating the phone verification, server response will be :server_internal_error (HTTP 500).

Procedures

📍 Retrieve all the pending procedures for the person.

GET api/v1/people/:person_id/procedures
Parameter Data type Description
person_id string Person's qualified identifier

Return value

  • When the person exists in the database, server response will be :ok (HTTP 200) and a JSON with all the pending procedures related to the person: (fields id.
Parameter Data type Description
id integer Procedure identifier at Census
type string Procedure type: Procedures::Registration, Procedures::PersonDataChange, Procedures::MembershipLevelChange, Procedures::DocumentVerification or Procedures::Cancellation
information string Payment method human name
  • When there is no person for the given person_id, server response will be :unprocessable_entity (HTTP 422) and an empty JSON.