Skip to content

API VoiceXML

Jump to bottom
Elias Anderlohr edited this page May 10, 2023 · 3 revisions

API Endpoint:

POST /user-exists.xml

Checks if a user exists in the database by their phone number.

Request Body

The request body must be in XML format and should contain the following parameters:

  • data: an object containing the following keys:
    • apikey: a string representing the API key
    • phone: a string representing the user's phone number

Example:

<data>
  <apikey>API_KEY</apikey>
  <phone>1234567890</phone>
</data>

Response Body

The response body will be in XML format and will contain the following parameters:

  • Header: an object containing the following keys:
    • Response: an object containing the following keys:
      • Code: a number representing the response code (200 if the user exists, 401 if the API key is invalid, or 500 if there is a server error)
      • Message: a string representing the response message
  • Body (optional): an object containing the following keys:
    • Farmer: an object containing the following keys:
      • Id: a number representing the user's ID
      • Language: a string representing the user's language

Example:

<Header>
  <Response>
    <Code>200</Code>
    <Message>User exists</Message>
  </Response>
</Header>
<Body>
  <Farmer>
    <Id>1</Id>
    <Language>en</Language>
  </Farmer>
</Body>

Potential Errors

  • 500 Server Error: There is a problem with the server.
  • 401 Unauthorized: The API key is invalid.
  • 401 User does not exist: The user does not exist in the database.

POST /certificates.xml

Retrieves a list of certificates for a user by their phone number and page number.

Request Body

The request body must be in XML format and should contain the following parameters:

  • data: an object containing the following keys:
    • apikey: a string representing the API key
    • phone: a string representing the user's phone number
    • page: a number representing the page number to retrieve (defaults to 1 if not provided)

Example:

<data>
  <apikey>API_KEY</apikey>
  <phone>1234567890</phone>
  <page>2</page>
</data>

Response Body

The response body will be in XML format and will contain the following parameters:

  • Header: an object containing the following keys:
    • Response: an object containing the following keys:
      • Code: a number representing the response code (200 if the certificates are found, 401 if the API key is invalid, or 500 if there is a server error)
      • Message: a string representing the response message
  • Body: an object containing the following keys:
    • Certificates: an object containing the following keys:
      • Count: a number representing the total number of certificates
      • Certificate: an array of certificate objects, each containing the following keys:
        • id: a number representing the certificate ID
        • farmer_id: a number representing the user's ID
        • certification_body: a string representing the certification body
        • certification_number: a string representing the certification number
        • expiry_date: a date representing the certificate expiry date

Example:

<Header>
  <Response>
    <Code>200</Code>
    <Message>Certificates found</Message>
  </Response>
</Header>

POST /certificate.xml

Retrieves a single certificate using the provided certificate ID and user phone number.

Request Body

The request body must be in XML format and should contain the following parameters:

  • data: an object containing the following keys:
    • apikey: a string representing the API key
    • phone: a string representing the user's phone number
    • certificateid: a string representing the certificate ID

Example:

<data>
  <apikey>API_KEY</apikey>
  <phone>1234567890</phone>
  <certificateid>ABCD1234</certificateid>
</data>

Response Body

The response body will be in XML format and will contain the following parameters:

  • Header: an object containing the following keys:
    • Response: an object containing the following keys:
      • Code: a number representing the response code (200 if the certificate is found, 401 if the API key is invalid or the user does not exist, or 500 if there is a server error)
      • Message: a string representing the response message
  • Body (optional): an object containing the following keys:
    • certificate: an object representing the retrieved certificate, containing various fields such as id, farmer_id, issued_at, and expires_at

Example:

<Header>
  <Response>
    <Code>200</Code>
    <Message>Certificate found</Message>
  </Response>
</Header>
<Body>
  <certificate>
    <id>12345</id>
    <farmer_id>1</farmer_id>
    <issued_at>2023-05-05 12:00:00</issued_at>
    <expires_at>2024-05-05 12:00:00</expires_at>
  </certificate>
</Body>

Potential Errors

  • 500 Server Error: There is a problem with the server.
  • 401 Unauthorized: The API key is invalid.
  • 401 User does not exist: The provided user phone number does not exist in the database.
  • 401 Certificate not found: The provided certificate ID does not exist or is not associated with the provided user phone number.
Clone this wiki locally