Update Photo

URI: https://api.cloudcard.us/photo/{id}

HTTP Method: PUT

Required Headers: X-Auth-Token (see: Authentication)

Example HTTP Request

{
    "status": "DOWNLOADED",
    "version": 12
}

Example Response

200 OK

{
	"id": 1,
	"status": "DOWNLOADED",
	"publicKey": "lotsOfRandomLettersAndNumbers"
}

The version field is optional but strongly recommended. Omitting the version field disables optimistic locking and increases the risk of updating a photo record that has already been updated by another user or process.

Potential Use Cases

Approve a Photo

To approve a photo, simply change the status field in the PUT request to "APPROVED":

{
    "status": "APPROVED",
    "version": 3
}

Deny a Photo

To deny a photo, simply change the status field in the PUT request to "DENIED":

You can also optionally specify reasons for your denial. These reasons are specified in Query String Parameters in the URL.

Denial Reasons are emailed to the cardholder to let them know what was wrong with the photo, so they can take a correct photo next time. However, the denial reasons for a specific photo are not currently saved, so they will not be accessible via the API or application later. Adding the ability to save the reasons for denial with the denied photos is a feature on our product roadmap.

Example Denial Reason URL

Here's an explanation of the parameters. All of these parameters are optional.

Parameter name	Explanation

Parameter name

Explanation

noteToCardholder

A note that will be included in the email to the user who submitted the photo that notifies them that their photo was denied.

otherReason

This field enables you to include a reason for the photo's denial that isn't covered by a Photo Requirement. This will be included in the list of reasons why the photo was denied that is included in the email to the user.

"Face Camera" and "Color Photo"

These parameters are the names of specific photo requirements that the user's photo violated. Simply provide the name of the requirement as the key, and "true" as the value, and that photo requirement will be included in the list of reasons the photo was denied when the user is sent an email.

You can find the list of photo requirements several different ways. The easiest would be to send a GET request to the /organization/{org id} endpoint, which would provide a list of your organization's photo requirements with their relevant fields.

Download a Photo externally

Typically a user of CloudCard downloads photos using the "Download Photos" button. This button takes care of marking the photos the user downloads as "DOWNLOADED". However, if you download a photo through the API without the use of this button (which is a perfectly legitimate use case of our API) you will need to mark the photos done yourself. Simply make a request to this endpoint with a status of "DOWNLOADED" and that will take the photo out of the APPROVED list for the next download run.

Allowed Photo Statuses

PENDING
APPROVED
DENIED
READY_FOR_DOWNLOAD
DOWNLOADED
DONE
ON_HOLD
ENROUTE
DISCARDED