SDK reference

This page describes parameters, captures, upload responses and retry conditions. Platform-specific signatures are documented in the React Native, Capacitor and native guides.

Configuration

Parameter	Type	Capacitor	React Native	Description
apiKey	string	required	required	SDK API key provided for your company.
baseUrl	string	required	optional	URL ending in /certificall/. React Native default: production.
appVersion	string	required	optional	Your application's version. React Native default: 1.0.0.

With Capacitor, call initialize(options). With React Native, call configure(options). Wait for the promise to resolve before any capture or upload. Set baseUrl explicitly to control which environment is used.

takePhoto()

const photo = await CertificallTrust.takePhoto({
  reportToken: 'JOB-2026-001',
  metadata: { site: 'Paris', zone: 'A1' },
});

The options object is optional. The method checks the device, opens its camera and returns a local capture CapturedPhoto. No case is created before upload.

Parameter	Type	Required	Description
reportToken	string	no	Your business reference, returned on upload and in webhook reportId. Limit it to 255 characters.
metadata	Record<string, string>	no	Key-value pairs attached to the case created on upload.

For metadata, use at most 20 keys, each up to 40 characters, with text values up to 500 characters. Keys cannot contain [ or ]. Convert numbers and booleans to text ("42", "true").

Invalid metadata are discarded during upload and reported as METADATA_DROPPED; they do not, on their own, prevent certification. See also Case metadata.

CapturedPhoto

Field	Type	Description
captureId	string	Capture UUID, used to recognize retries.
capturedAt	string	Capture time, ISO 8601 UTC.
sessionId	string	Session identifier generated by the SDK. Keep it without rebuilding it.
image	CapturedImage	Base64 JPEG image, format and dimensions.
exif	object or null	Available EXIF data.
signals	CaptureSignals	Trust data frozen at capture time.
debugBuild	boolean	Indicates a capture from a development build.
reportToken	string or null	Business reference provided at capture time.
metadata	object or null	Metadata provided at capture time.
target	null	Reserved field; keep the value returned by the SDK.
proof	null	Reserved field; keep the value returned by the SDK.

Image

Field	Type	Description
image.base64	string	Base64 JPEG content, required for upload.
image.format	string	jpeg.
image.width	number	Width in pixels.
image.height	number	Height in pixels.

Trust data

The SDK automatically collects these data from configuration onward, then attaches them to the capture. You do not need to collect or add them yourself.

Field	Content
signals.historyPositions	Positions: timestamp, lat, long, accuracy, altitude, speed, heading.
signals.historyMotions	Motion: timestamp, acceleration (x, y, z) and rotation (alpha, beta, gamma).
signals.device	manufacturer, model, name, platform, os, osVersion, appVersion, isVirtual, batteryLevel, isCharging.
signals.network	connectionType, wifiIp, carrierIp. Addresses can be null.

History timestamps are in milliseconds. Coordinates are in degrees, accuracy and altitude in metres, speed in metres per second and heading in degrees. Acceleration is in m/s², including gravity; rotation is in degrees per second. Battery is a fraction between 0 and 1 (0.8 for 80%), or null if unknown.

These data remain those of capture time, even with a deferred upload. Arrays can be empty when no signals could be collected; review the warnings in the upload response.

sendPhoto()

Pass the complete capture returned by takePhoto(), or restored from your storage:

// React Native
const sent = await CertificallTrust.sendPhoto(photo);

// Capacitor
const sent = await CertificallTrust.sendPhoto({ photo });

Certificall creates the case, adds the photo, closes it and produces the PDF certificate. The SentPhoto response is returned after this workflow. Missing trust data are reported in warnings.

Call sendPhoto() right after the capture, as soon as the network allows. A photo uploaded more than 10 minutes after it was taken carries the "no internet connection" banner on its certificate.

SentPhoto

Field	Type	Description
captureId	string	Identifier of the uploaded capture.
itemId	string	Certificall photo identifier.
caseId	string	Identifier of the created case.
reportToken	string (optional)	Business reference echoed back.
imageUrl	string	Image URL.
pdfUrl	string	PDF certificate URL.
geoloc	{ lat: number, lng: number } (optional)	Coordinates used for the photo. With NO_POSITION, do not use them as a real location.
createdAt	string	Server-side creation time, ISO 8601.
warnings	{ code: string, message: string }[]	Missing, discarded or replaced data; empty array if there are no warnings.

Additional fields returned by Certificall are passed through by the SDK. Tolerate additional fields and warning codes.

Certificate and analysis

The response does not contain a score. The case webhook delivers the case when it closes; the analysis result webhook subsequently delivers the trust result. You can link them to your system with reportToken, returned as reportId.

Storage and retries

The SDK does not maintain a persistent queue or schedule automatic retries. Your application handles storage and upload scheduling.

1. Save the complete object returned by takePhoto(), using JSON.stringify(photo) for JavaScript bridges. Include image.base64.
2. Read it back with JSON.parse(serializedPhoto) when upload becomes possible.
3. Call sendPhoto() with the restored capture, without changing its identifiers or signals.
4. Remove the capture from your queue after a successful response, keeping any identifiers and links your application needs.

If connectivity is interrupted or the application closes before receiving the response, send the same capture again. If it has already been certified, you receive the same case and photo identifiers and the same certificate link. A new takePhoto() call carries a different captureId and creates another case.

Situation	Action
NETWORK_UNAVAILABLE	Keep the capture and retry when Certificall is reachable.
SERVER_REJECTED, reason CAPTURE_IN_PROGRESS, HTTP 409	The same capture is being certified. Retry after a few minutes.
SERVER_REJECTED, reason CAPTURE_NOT_CERTIFIED, HTTP 503	The photo was received but certification failed. Keep it and retry later.
HTTP 429	Space out uploads and retry after the rate-limiting window.
Other server error 5xx	Keep the capture and retry with a delay.
Invalid key or blocked company	Correct the situation before resuming uploads.

If an initial attempt remains unfinished for more than 10 minutes, a retry can start again in a new case. Returning the same case applies to an already-certified capture; an unfinished case is not reused after that interval.

Preserve the capture

Keep the JSON produced by the SDK as-is. Do not replace signals with data from upload time or remove captureId: it allows Certificall to recognize a retry.

Warnings

A warning is not an upload failure: a successful response with warnings means the photo was saved and certified. Missing data can lower the trust score. Your application can notify the user or offer a new capture according to your business needs.

Code	Meaning
NO_POSITION	No usable position; the photo has no location.
NO_MOTION	No motion collected.
NO_DEVICE	Device model missing or unreadable.
NO_BATTERY	Battery level unknown.
NO_IP	No IP address provided.
CAPTURE_UNREADABLE	Capture description missing or unreadable; signals cannot be used.
CAPTURE_ID_GENERATED	Capture identifier missing or invalid, replaced by the server. Retrying this upload does not benefit from recognition by the original identifier.
CAPTURED_AT_MISSING	Capture time missing or invalid; reception time is used.
SIGNALS_DROPPED	Some unreadable positions or motion entries were discarded.
SIGNALS_TRUNCATED	More than 200 positions or motion entries sent; the 200 most recent in each history are kept.
METADATA_DROPPED	Invalid metadata; the case is created without those metadata.

The message values are explanations in English. Use codes to drive your logic and translations.

Errors

Capture and upload codes

Code	Operation	Action
NOT_INITIALIZED	Capture or upload	Configure the SDK and wait for initialization to finish.
DEVICE_NOT_TRUSTED	Capture	Read reasons and explain the device refusal to the user.
CAPTURE_CANCELLED	Capture	The user left the camera. Nothing is uploaded.
NO_CAMERA	Capture	No camera available; the photo library is not offered instead.
CAPTURE_FAILED	Capture	The camera did not return a usable photo; capture again.
INVALID_PHOTO	Upload through a bridge or iOS restoration	Pass the complete object returned by takePhoto().
NETWORK_UNAVAILABLE	Upload	Keep the capture for a retry.
SERVER_REJECTED	Upload	Read the HTTP status and server reason, then apply the corresponding strategy.

Configuration or permission errors can also originate from your platform's APIs. Check permissions and the presence of configuration parameters.

Read additional information

Platform	Code	Device refusal reasons	Server status and reason
Capacitor	error.code	error.data.reasons	error.data.status, error.data.reason
React Native	error.code	error.userInfo.reasons	error.userInfo.status, error.userInfo.reason
Swift	CertificallSDKError.code(of: error)	CertificallSDKError.reasons	httpStatus, serverCode on the typed error
Kotlin	CertificallError.codeOf(error)	DeviceNotTrustedException.reasons	SendPhotoException.httpStatus, SendPhotoException.serverCode

Server rejections

HTTP refusals use SERVER_REJECTED. The reason can be absent; do not rely only on the message text.

HTTP status	Reason when provided	Action
400	INVALID_CAPTURE if the image is missing	Check that the capture and its image are complete.
401	Missing, invalid, inactive or expired key	Check the environment key and its renewal.
403	DEBUG_BUILD_REJECTED	Take a new photo with a distribution build for production.
409	CAPTURE_IN_PROGRESS	Retry the same capture later.
409	CAPTURE_ID_TAKEN	The identifier is already used by another capture; take a new photo.
423	Blocked company	Have the company's access restored before resuming uploads.
429	Request limit reached	Space out uploads.
503	CAPTURE_NOT_CERTIFIED	Keep the capture and retry later.

A 2xx HTTP response without a case result can also produce SERVER_REJECTED. Check baseUrl, especially its /certificall/ suffix, and keep the capture until upload succeeds.