Onboarding Buddy API FAQ

The following FAQ is based on the OpenAPI specification for the Onboarding Buddy API, which provides services for validation, file management, and sanctions checks. Below are answers to common questions about the API's functionality, endpoints, and usage.

General Questions

Q: What is the Onboarding Buddy API?

A: The Onboarding Buddy API is a set of services designed to assist with validation, file management, and sanctions checks. It includes endpoints for validating email addresses, mobile numbers, IP addresses, and browser user agents, managing file uploads and generation, and performing sanctions checks for individuals, entities, crypto wallets, vessels, and aircraft.

Q: What is the base URL for the API?

A: The base URL for the Onboarding Buddy API is https://api.onboardingbuddy.co.

Q: What version of OpenAPI is used in the specification?

A: The API uses OpenAPI version 3.0.1.

Q: What authentication is required to use the API?

A: All endpoints require three authentication headers: ob-app-key (App Key), ob-api-key (Api Key), and ob-api-secret (Api Secret).

Validation Service

Q: What types of data can I validate using the API?

A: The API supports validation for:

• Email addresses (/validation-service/validation/email)
• Mobile numbers (/validation-service/validation/mobile)
• IP addresses (/validation-service/validation/ipaddress)
• Browser user agents (/validation-service/validation/browser)

Q: Can I validate multiple values at once?

A: Yes, the API supports batch validation for email addresses, mobile numbers, IP addresses, and browsers. Use the following endpoints:

• Email addresses: POST /validation-service/batch/email-address
• Mobile numbers: POST /validation-service/batch/mobile
• IP addresses: POST /validation-service/batch/ip-address
• Browsers: POST /validation-service/batch/browser

Q: How do I check the status of a batch validation request?

A: You can poll the status of a batch using the GET /validation-service/batch/poll/{batchId} endpoint, providing the batchId returned from the batch submission.

Q: How do I retrieve the results of a batch validation?

A: Use the following endpoints to retrieve batch results, specifying the batchId:

• Email addresses: GET /validation-service/batch/email-address/{batchId}
• Mobile numbers: GET /validation-service/batch/mobile/{batchId}
• IP addresses: GET /validation-service/batch/ip-address/{batchId}
• Browsers: GET /validation-service/batch/browser/{batchId}

Q: What happens if my validation request contains errors?

A: If the payload is null or contains validation errors, the API will return a 400 status code with details in the response.

Q: What information is returned for an email validation?

A: The email validation response (EmailAddressResponseM) includes fields like emailAddress, emailStatus, freeEmail, domain, mxFound, mxRecord, isDisposableDomain, and sanctionRecord, along with metadata like messageId, correlationId, and checkStatus.

Q: What details are provided in a mobile number validation response?

A: The mobile number validation response (MobileNumberResponseM) includes fields such as mobileNumber, valid, localFormat, internationalFormat, countryPrefix, countryCode, carrier, lineType, and checkStatus.

Q: What does the IP address validation response include?

A: The IP address validation response (IpAddressResponseM) includes fields like ipAddress, isoCode, country, threat, riskLevel, isTorAddress, isVpnAddress, and checkStatus.

Q: What information is returned for browser validation?

A: The browser validation response (BrowserResponseM) includes fields such as userAgent, simpleSoftware, software, softwareName, operatingSystem, operatingSystemVersion, isAbusive, and checkStatus.

File Service

Q: What file-related operations are supported by the API?

A: The API supports:

• Uploading files: POST /file-service/upload
• Downloading files: GET /file-service/download/{fileGlobalId}
• Generating images: POST /file-service/generate/image
• Generating videos: POST /file-service/generate/video
• Polling file generation status: GET /file-service/generate/poll/{globalId}
• Retrieving file metadata: GET /file-service/management/{fileGlobalId}
• Deleting files: DELETE /file-service/management/{fileGlobalId}
• Listing all files for an organization: GET /file-service/management
• Searching files using vector search: POST /file-service/search
• Performing document-based Retrieval-Augmented Generation (RAG): POST /file-service/query/rag

Q: How do I upload a file?

A: Use the POST /file-service/upload endpoint with a multipart/form-data request containing the file as a binary. The response (FileUploadResponseM) includes metadata like globalId, fileName, fileHash, mimeType, and fileStatus.

Q: Can I generate images or videos using the API?

A: Yes, you can generate images using POST /file-service/generate/image with a prompt, and videos using POST /file-service/generate/video with a prompt or an image and prompt. Both return a GenerateFileResponseM with a fileGlobalId and status.

Q: How do I check the status of a file generation request?

A: Use the GET /file-service/generate/poll/{globalId} endpoint, providing the globalId from the generation request. The response (PollFileResponseM) includes fileStatus, fileHash, and createdDate.

Q: How can I download a file?

A: Use the GET /file-service/download/{fileGlobalId} endpoint with the fileGlobalId. The response (FileDownloadRecordM) includes a preSignedUrl for downloading the file, valid until preSignedUrlUtc.

Q: What happens if I request a file that doesn’t exist?

A: The GET /file-service/download/{fileGlobalId} endpoint will return a 404 status code if the requested file does not exist.

Q: How do I delete a file?

A: Use the DELETE /file-service/management/{fileGlobalId} endpoint with the fileGlobalId. A successful deletion returns a 204 status code.

Q: Can I search for files?

A: Yes, use the POST /file-service/search endpoint with a SearchFileRequestM payload containing a searchString. The response (SearchFileResponseM) returns a list of matching file records with metadata like fileName, mimeType, and distance.

Q: What is the Document RAG feature?

A: The POST /file-service/query/rag endpoint allows you to perform a Retrieval-Augmented Generation (RAG) query on a specific file, identified by fileGlobalId, using a searchString. The response (RagQueryResponseM) includes generatedText based on the query.

Sanctions Service

Q: What types of sanctions checks can I perform?

A: The API supports sanctions checks for:

• Individuals: POST /sanction-service/check/individual
• Entities: POST /sanction-service/check/entity
• Crypto wallets: POST /sanction-service/check/crypto-wallet
• Vessels: POST /sanction-service/check/vessel
• Aircraft: POST /sanction-service/check/aircraft

Q: What information is required for an individual sanctions check?

A: The IndividualSanctionsCheckRequestM requires firstName, lastName, and optionally birthYear.

Q: What details are returned in a sanctions check response?

A: Sanctions check responses (e.g., IndividualSanctionsCheckResponseM, EntitySanctionsCheckResponseM) include fields like matched (boolean), match or results (array of sanction records), and metadata like messageId, correlationId, and inError. Sanction records may include details like fullName, program, aliasList, nationality, and secondarySanctionsRisk.

Q: What happens if a sanctions check request is invalid?

A: If the payload is null or contains validation errors, the API returns a 400 status code.

Error Handling

Q: What does a 400 error mean?

A: A 400 status code indicates that the request payload is null or contains validation errors. Check the response body for specific error messages.

Q: What does a 404 error mean in the file service?

A: A 404 status code from the GET /file-service/download/{fileGlobalId} endpoint means the requested file does not exist.

Security and Authentication

Q: How is authentication handled in the API?

A: All endpoints require three headers: ob-app-key, ob-api-key, and ob-api-secret. These must be included in every request for authentication.

Q: What happens if I don’t provide the required authentication headers?

A: Without the required AppKey, ApiKey, and ApiSecret headers, the API will reject the request, likely with an authentication error.

Schema and Data Models

Q: What is the structure of a batch validation response?

A: The SubmitBatchResponseM schema includes fields like batchId, batchStatus (enum: 1, 2, 3, 4), messageId, correlationId, idempotencyKey, inError, and messages.

Q: What fields are included in a file record?

A: The FileRecordM schema includes fields like globalId, organisationGlobalId, applicationGlobalId, fileName, mimeType, originType, fileSize, fileStatus, fileHash, prompt, title, description, tags, and createdDate.

Q: How are idempotency keys used in the API?

A: Many endpoints support an idempotencyKey in the request payload to ensure that repeated requests with the same key do not result in duplicate actions. This is useful for retrying requests safely.

Example Usage

Q: Can you provide an example of an email validation request?

A: Here’s an example request to POST /validation-service/validation/email:

{
  "emailAddress": "support@onboardingbuddy.co",
  "correlationId": "12345",
  "idempotencyKey": "abcde"
}
    

The response might look like:

{
  "emailAddress": "support@onboardingbuddy.co",
  "emailStatus": "Valid",
  "freeEmail": false,
  "domain": "onboardingbuddy.co",
  "mxFound": true,
  "mxRecord": "mail.onboardingbuddy.co",
  "isDisposableDomain": false,
  "checkStatus": "Matched"
}
    

Q: Can you provide an example of a file upload request?

A: For POST /file-service/upload, send a multipart/form-data request with a file. The response might be:

{
  "globalId": "ff0fd726-6ccb-4a2b-beff-2519a0a2b696",
  "fileName": "example.png",
  "mimeType": "image/png",
  "fileSize": 1543425,
  "fileStatus": "PROCESSED",
  "fileHash": "zJBDrBEkTUUwuCcoEPD8K...",
  "active": true
}
    

Q: Can you provide an example of an image generation request?

A: For POST /file-service/generate/image:

{
  "prompt": "A space rocket 3 seconds into launch heading into the night sky",
  "idempotencyKey": "f1bcbcb3-6d47-455e-afae-ac236bf73c11"
}
    

The response might be:

{
  "fileGlobalId": "ff0fd726-6ccb-4a2b-beff-2519a0a2b696",
  "status": "SUBMITTED",
  "idempotencyKey": "f1bcbcb3-6d47-455e-afae-ac236bf73c11"
}
    

If you have further questions or need clarification on specific endpoints or schemas, please let us know!

Email us at support@onboardingbuddy.co

Code samples using C#, Python, Typescript can be found in our Getting Started documentation