{ "openapi": "3.0.1", "info": { "title": "Bulk Geo Addressing API", "description": "Precisely Data Integrity Suite offers bulk processing for address validation and geocoding. In bulk processing, it takes a big input file and returns the output file. These Bulk Geo Addressing APIs are asynchronous in nature.\n\n\nThe flow of the Bulk Geo Addressing APIs will be as follows:\n- Use the `File Upload URL API` to get the pre signed URL to upload the file to AWS S3. The upload url will be valid only for next 10 minutes.\n- Then upload the file using the pre signed url.\n- Then take the file ID, returned by `File upload URL API` and use the `Bulk Verify/Geocode API` to submit the job. It will return the url for `Status API`.\n- Using the `Status API`, you can check the current status of the processing. Statuses can be as follows:\n - Scheduled: Job is scheduled and waiting to be picked.\n - Running: Job is running.\n - Completed: Job is completed.\n - Failed: Job is failed.\n- When job gets completed, `Status API` returns the download url for the output file. This download url is valid for next 10 minutes. If you want to access the file again after 10 minutes, then you need\nto hit the status APi again and it will return the new download url which again will be valid for next 10 minutes.\n- There are 2 more APIs which is to get the list of uploaded files (`List Uploaded Files API`) and to delete any of the uploaded files (`Delete File API`) from S3.\n\n
\n Error Codes\n\nAPIs will return the following error codes in case of any error:\n\n\n| Error Code | Description\n|----------------------------|-------------------------------------------------------\n| DIS-1001 | Unauthorized, Invalid token\n| DIS-1002 | Not Authorized to access this API\n| DIS-1003 | Issue with internal services\n| DIS-1004 | Workspace Id is missing from Bearer Token\n| DIS-1005 | Rate limit exceeded\n| DIS-1006 | Unauthorized, Invalid key/secret\n| DIS-1007 | API quota has been permanently exhausted. No further requests are allowed for trial user\n| DIS-1009 | Access blocked due to too many failed attempts. Please try again after sometime\n| DIS-1010 | Workspace has been expired\n| DIS-LI-1011 | Service is not available to serve the request\n| DIS-LI-1013 | JWT token is not valid\n| DIS-LI-1018 | Request Body is not valid\n| DIS-LI-1019 | Request body is not specified in the request\n| DIS-LI-1024 | Workspace ID is not valid in JWT token\n| DIS-LI-1030 | Invalid data option in customPreferences\n| DIS-LI-1051 | Job id is incorrect\n| DIS-LI-1052 | File id is incorrect\n| DIS-LI-1053 | Mandatory input headers are missing in input file or the file is not UTF-8 encoded\n| DIS-LI-1054 | Duplicate input headers found\n
\n", "version": "1.0" }, "servers": [ { "url": "https://api.cloud.precisely.com" } ], "tags": [ { "name": "Bulk Geo Addressing", "description": "This API bulk geocodes or performs address verification of the address file." } ], "paths": { "/v1/bulk-geocode": { "post": { "tags": [ "Bulk Geo Addressing" ], "summary": "Bulk geocodes the addresses file", "description": "This API geocodes the addresses file. It takes file id corresponding to uploaded file and returns the url to check the status of geocoding job.", "operationId": "bulkGeocode", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "The X-Request-Id header is optional but incredibly useful for developers. It serves as a unique identifier for requests within our system. When you encounter any problems with your requests, providing us with the X-Request-Id will enable us to pinpoint the specific request in question without the need for extensive manual searching. This means faster and more efficient troubleshooting. The maximum allowed length is 38 characters.", "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174005" }, { "name": "X-CASS-FLOW", "in": "header", "description": "The X-CASS-FLOW header is optional and used for the identification of cass flow.For normal flow it can be empty or null ,but for cass flow we can have one of the 2 values: with_report,no_report", "schema": { "type": "string" }, "example": " " } ], "requestBody": { "description": "This API geocodes the addresses file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkGeocodeRequest" }, "examples": { "example": { "value": { "fileId": "8d907c8c-5b63-417f-b69f-2d33dbdd2fcd" } }, "withReportDetails": { "value": { "fileId": "8d907c8c-5b63-417f-b69f-2d33dbdd2fcd", "reportDetails": { "listProcessorName": "Precisely Software Inc.", "listNameId": "file_1", "totalList": "1", "mailingAddress": "123 Main St, New York, NY 10001 USA" } } }, "withDelimiter": { "value": { "fileId": "8d907c8c-5b63-417f-b69f-2d33dbdd2fcd", "delimiter": "|" } }, "withDelimiterAndPreference": { "value": { "fileId": "8d907c8c-5b63-417f-b69f-2d33dbdd2fcd", "delimiter": "|", "preferences": { "maxResults": 1, "returnAllInfo": true, "factoryDescription": { "label": "", "featureSpecific": {} }, "clientLocale": "en_US", "clientCoordSysName": "", "distance": { "value": 150, "distanceUnit": "METER" }, "streetOffset": { "value": 7, "distanceUnit": "METER" }, "cornerOffset": { "value": 7, "distanceUnit": "METER" }, "fallbackToGeographic": true, "fallbackToPostal": true, "matchMode": "", "returnOfAdditionalFields": [], "originXY": [], "customPreferences": {} } } } } } }, "required": true }, "responses": { "202": { "description": "Bulk Geocode Job Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkGeocodeResponse" }, "examples": { "example": { "value": { "statusUrl": "https://api.cloud.precisely.com/v1/bulk/jobs/180c0892-affc-4f7a-b1c3-d5e965a6eefb" } } } } } }, "400": { "description": "Invalid request for Bulk Geocode API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_REQUEST", "errorMessage": "Invalid File Id (DIS-LI-1052)" } ] } } } } } }, "401": { "description": "Unauthorized: Invalid token for Bulk Geocode API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_TOKEN", "errorMessage": "Unauthorized (DIS-1001)" } ] } } } } } }, "403": { "description": "Forbidden for Bulk Geocode API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "FORBIDDEN", "errorMessage": "You do not have permission to access this API (DIS-1002)" } ] } } } } } }, "429": { "description": "Too many requests for Bulk Geocode API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "TOO_MANY_REQUESTS", "errorMessage": "Rate limit exceeded (DIS-1005)" } ] } } } } } }, "500": { "description": "Internal Server Error for Bulk Geocode API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INTERNAL_ERROR", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-1003)" } ] } } } } } } }, "deprecated": true, "security": [ { "bearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/bulk-verify": { "post": { "tags": [ "Bulk Geo Addressing" ], "summary": "Performs address verification and standardization of the addresses file", "description": "This API performs address verification and standardization of the addresses file. It takes file id corresponding to uploaded file and returns the url to check the status of address verification job.", "operationId": "bulkVerify", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "The X-Request-Id header is optional but incredibly useful for developers. It serves as a unique identifier for requests within our system. When you encounter any problems with your requests, providing us with the X-Request-Id will enable us to pinpoint the specific request in question without the need for extensive manual searching. This means faster and more efficient troubleshooting. The maximum allowed length is 38 characters.", "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174003" }, { "name": "X-CASS-FLOW", "in": "header", "description": "The X-CASS-FLOW header is optional and used for the identification of cass flow.For normal flow it can be empty or null ,but for cass flow we can have one of the 2 values: with_report,no_report", "schema": { "type": "string" }, "example": " " } ], "requestBody": { "description": "This API performs address verification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkGeocodeRequest" }, "examples": { "example": { "value": { "fileId": "8d907c8c-5b63-417f-b69f-2d33dbdd2fcd" } }, "withReportDetails": { "value": { "fileId": "8d907c8c-5b63-417f-b69f-2d33dbdd2fcd", "reportDetails": { "listProcessorName": "Precisely Software Inc.", "listNameId": "file_1", "totalList": "1", "mailingAddress": "123 Main St, New York, NY 10001 USA" } } }, "withDelimiter": { "value": { "fileId": "8d907c8c-5b63-417f-b69f-2d33dbdd2fcd", "delimiter": "|" } }, "withDelimiterAndPreference": { "value": { "fileId": "8d907c8c-5b63-417f-b69f-2d33dbdd2fcd", "delimiter": "|", "preferences": { "maxResults": 1, "returnAllInfo": true, "factoryDescription": { "label": "", "featureSpecific": {} }, "clientLocale": "en_US", "clientCoordSysName": "", "distance": { "value": 150, "distanceUnit": "METER" }, "streetOffset": { "value": 7, "distanceUnit": "METER" }, "cornerOffset": { "value": 7, "distanceUnit": "METER" }, "fallbackToGeographic": true, "fallbackToPostal": true, "matchMode": "", "returnOfAdditionalFields": [], "originXY": [], "customPreferences": {} } } } } } }, "required": true }, "responses": { "202": { "description": "Bulk Verify Job Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkGeocodeResponse" }, "examples": { "example": { "value": { "statusUrl": "https://api.cloud.precisely.com/v1/bulk/jobs/180c0892-affc-4f7a-b1c3-d5e965a6eefb" } } } } } }, "400": { "description": "Invalid request for Bulk Verify API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_REQUEST", "errorMessage": "Invalid File Id (DIS-LI-1052)" } ] } } } } } }, "401": { "description": "Unauthorized: Invalid token for Bulk Verify API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_TOKEN", "errorMessage": "Unauthorized (DIS-1001)" } ] } } } } } }, "403": { "description": "Forbidden for Bulk Verify API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "FORBIDDEN", "errorMessage": "You do not have permission to access this API (DIS-1002)" } ] } } } } } }, "429": { "description": "Too many requests for Bulk Verify API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "TOO_MANY_REQUESTS", "errorMessage": "Rate limit exceeded (DIS-1005)" } ] } } } } } }, "500": { "description": "Internal Server Error for Bulk Verify API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INTERNAL_ERROR", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-1003)" } ] } } } } } } }, "deprecated": true, "security": [ { "bearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/bulk/jobs": { "get": { "tags": [ "Bulk Geo Addressing" ], "summary": "Provide list of jobs that are in scheduled or running state for particular user", "description": "This API returns a list of bulk geocode/verify jobs for the authenticated user.\nYou can optionally filter jobs by status (scheduled, running, or all).\nOnly the 'status' query parameter is accepted; any other query parameters will result in a 400 Bad Request error.", "operationId": "listJobs", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "The X-Request-Id header is optional but incredibly useful for developers. It serves as a unique identifier for requests within our system. When you encounter any problems with your requests, providing us with the X-Request-Id will enable us to pinpoint the specific request in question without the need for extensive manual searching. This means faster and more efficient troubleshooting.", "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174004" }, { "name": "status", "in": "query", "description": "Filter jobs by status. Allowed values: 'scheduled', 'running', or 'all'. If not provided, returns all jobs.", "required": false, "schema": { "type": "string", "enum": [ "scheduled", "running", "all" ] }, "example": "scheduled" } ], "responses": { "200": { "description": "List of scheduled/running jobs returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueuedJobsResponse" }, "examples": { "example": { "value": { "jobs": [ { "jobId": "bd80fe36-d7f4-4bc8-b1a2-4d25c04f842e", "emailId": "sample_user@precisely.com", "fileId": "bb1cef64-1fb1-4433-a440-e62252cd2fe8", "fileName": "SampleFile", "status": "SCHEDULED", "submittedAt": "2025-11-03T09:39:17.128Z" }, { "jobId": "617c3dbb-4c56-4ec7-a9cb-962450a3022e", "emailId": "sample_user@precisely.com", "fileId": "bb1cef64-1fb1-4433-a440-e62252cd2fe8", "fileName": "SampleFile", "status": "RUNNING", "submittedAt": "2025-11-03T09:39:10.849Z" } ] } } } } } }, "400": { "description": "Bad Request - Invalid query parameters. Only 'status' parameter is allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_CLIENT_INPUT", "errorMessage": "Request is not valid (DIS-LI-1018)" } ] } } } } } }, "401": { "description": "Unauthorized: Invalid token for List Bulk Job API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_TOKEN", "errorMessage": "Unauthorized (DIS-1001)" } ] } } } } } }, "403": { "description": "Forbidden for List Bulk Job API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "FORBIDDEN", "errorMessage": "You do not have permission to access this API (DIS-1002)" } ] } } } } } }, "429": { "description": "Too many requests for List Bulk Job API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "TOO_MANY_REQUESTS", "errorMessage": "Rate limit exceeded (DIS-1005)" } ] } } } } } }, "500": { "description": "Internal Server Error for List Bulk Job API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INTERNAL_ERROR", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-1003)" } ] } } } } } } }, "deprecated": true, "security": [ { "bearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/bulk/jobs/{jobId}": { "get": { "tags": [ "Bulk Geo Addressing" ], "summary": "Checks status of requested job of bulk geocode/verify", "description": "This API checks status of requested job of bulk geocode/verify. It takes the job id provided when we submit bulk geocode/verify job and returns the status of the job. Once the job is completed it returns download url of output file along with status.", "operationId": "getStatus", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "The X-Request-Id header is optional but incredibly useful for developers. It serves as a unique identifier for requests within our system. When you encounter any problems with your requests, providing us with the X-Request-Id will enable us to pinpoint the specific request in question without the need for extensive manual searching. This means faster and more efficient troubleshooting.", "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174004" }, { "name": "jobId", "in": "path", "description": "job id of bulk geocode or verify", "required": true, "schema": { "type": "string" }, "example": "8d907c8c-5b63-417f-b69f-2d33dbdd2fcd" } ], "responses": { "200": { "description": "Status got successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStatusResponse" }, "examples": { "example": { "value": { "status": "COMPLETED", "downloadUrl": "https://us-east-1-bulk-api.s3.us-east-1.amazonaws.com/test/test_user_1%40precisely.com/output/91ff044f-cc42-4c8a-a781-43fdc4a14963/test_file%3A%3A16bb27b6-9f71-4bf2-8c34-19d4a7b6a035.csv?X-Amz-Security-Token=IQoJb3JpZ2luX2VjEAMaCXVzLWVhc3QtMiJHMEUCIQDfJzxD1buoQg3Fp0jUfnjrPQRzA0bmD6O%2FeN%2BZAQc2tAIgRttKfyWQy8THMc0BrfwsuSNDMTBFS20oett2EGnnyQEqjQUI7f%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FARADGgw1MDg3NDc3ODk4NzQiDGdtz11Dx2e%2FouDkdirhBEYLDfQRUlSbYElOfuxnfKudb5BVA284Eb34UNgCRab13ectiAyoyYUIX74%2BTi7hnzDvMnarybgJza55905L2hXg5AHwdFqQPNjXyawhaikvluV3q%2BHyIP2vTE%2FUXMRFEiCmIs5HXAz99atDghpZPVjV7cGNMRAKN8SFoEtaDLJ%2FUvA1EUskqL0CsZfBybR7lSOszVfQ6CypQ1TVAMk9t9jpj%2BLwUWLIxk7usggoWzQdvMV%2FjcvDNZkmk0UoveM5CFHGt98mru2l%2FqW96nV8ld3IOyxqMx1f8c3Upcdbi416Ln8CjphttbVSNUONluzdVtTndf87zEC5O%2B810x%2FDLqDAmOZ5Q%2Bgs3YCtpxwhhw%2FjwVUv318O0yqQVZs0zL0ZuJOWAZqIMKIzRhiEJjihRkbzMqWtPQEG%2BXzgWMPficJQRqjs9i7WnmTjrZ0aaOXNqZ2KrGnj2AjMKtnrmj5FYM6tYq850o%2FzmpWoRtefHf0NxzYTJCswRVz7fG%2FZ%2BbBdT9rO%2FTMDw5QI9U07VkCbeGfc0hFK5Spaee%2F8PTJyDrlESLN0AyTmk3zaEGR6onoysyQxduHKx8HTVJYr2VQcmZM1ltaml9Z7d5hIZQJ6n0FJ5fXwNu0p%2BJSewbDwDImTgNQm7XMbHEpfv%2BZ2lAnA07lyxMJq%2FIjJ5G2%2BaBuFb7%2FR5HtGzq0VmGd0AWe0EtgNlGFgMnAyLlpZBOsl1u6vmB3%2BKw5ID5a7aRbUp4IHdlOBr2BHLu%2BFU9Vl8sUUxo3rfyqsJFnriavWH5aP39Mbm3rDb7dcTDHkMO%2FAqcbo3L9YgTDh0bCoBjqaAXLMcTNBcNiDQ8Scpn%2FidqSQ2u1sfn8jbmp3ERj%2FU4VeIkxlxkpcBYHZ0ujmHu3LDDeD8ze9190Ck9awsVjnKcWc2cf20p6UJ34%2Ff2LvS%2BvnkprNn1sNZAYPC6DbfC%2FUzv6SjN2%2FVCWn1hM6h7WJwjHIcFY0VRF%2BdkHzHFn0d8UvJAHE1yQELUAl8DF0JX60P7ZNbDvJ8hC4gu4%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20230921T115717Z&X-Amz-SignedHeaders=host&X-Amz-Expires=599&X-Amz-Credential=ASIAXM453GYZCWAGCK66%2F20230921%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Signature=f854694713bcc466fe5b358a1b0bff49446b2f4689422405e213d4ab3ef8e4ea", "message": "This download URL will be valid for the next 10 mins." } } } } } }, "400": { "description": "Invalid request for Bulk Job Status API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_REQUEST", "errorMessage": "Invalid Job Id (DIS-LI-1051)" } ] } } } } } }, "401": { "description": "Unauthorized: Invalid token for Bulk Job Status API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_TOKEN", "errorMessage": "Unauthorized (DIS-1001)" } ] } } } } } }, "403": { "description": "Forbidden for Bulk Job Status API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "FORBIDDEN", "errorMessage": "You do not have permission to access this API (DIS-1002)" } ] } } } } } }, "429": { "description": "Too many requests for Bulk Job Status API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "TOO_MANY_REQUESTS", "errorMessage": "Rate limit exceeded (DIS-1005)" } ] } } } } } }, "500": { "description": "Internal Server Error for Bulk Job Status API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INTERNAL_ERROR", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-1003)" } ] } } } } } } }, "deprecated": true, "security": [ { "bearerAuth": [] }, { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Bulk Geo Addressing" ], "summary": "Cancels requested job of bulk geocode/verify which is in Scheduled state", "description": "This API cancels Scheduled state jobs of bulk geocode/verify.", "operationId": "cancelScheduledJob", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "The X-Request-Id header is optional but incredibly useful for developers. It serves as a unique identifier for requests within our system. When you encounter any problems with your requests, providing us with the X-Request-Id will enable us to pinpoint the specific request in question without the need for extensive manual searching. This means faster and more efficient troubleshooting.", "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174004" }, { "name": "jobId", "in": "path", "description": "job id of bulk geocode or verify", "required": true, "schema": { "type": "string" }, "example": "8d907c8c-5b63-417f-b69f-2d33dbdd2fcd" } ], "responses": { "200": { "description": "Request received for job cancellation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelJobResult" }, "examples": { "example": { "value": { "jobId": "fdb25e89-30c0-4fdb-b2b8-2c6e24736ad9", "message": "Request received for job cancellation" } } } } } }, "400": { "description": "Invalid JobId for cancellation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "BAD_REQUEST", "errorMessage": "Invalid Job Id (DIS-LI-1051)" } ] } } } } } }, "401": { "description": "Unauthorized: Invalid token for Cancel Bulk Job API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_TOKEN", "errorMessage": "Unauthorized (DIS-1001)" } ] } } } } } }, "403": { "description": "Forbidden for Cancel Bulk Job API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "FORBIDDEN", "errorMessage": "You do not have permission to access this API (DIS-1002)" } ] } } } } } }, "429": { "description": "Too many requests for Cancel Bulk Job API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "TOO_MANY_REQUESTS", "errorMessage": "Rate limit exceeded (DIS-1005)" } ] } } } } } }, "500": { "description": "Internal Server Error for Cancel Bulk Job API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INTERNAL_ERROR", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-1003)" } ] } } } } } } }, "deprecated": true, "security": [ { "bearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/files": { "get": { "tags": [ "Bulk Geo Addressing" ], "summary": "Gets the list of files which are available on S3 to be processed", "description": "This API gets the list of files which are available on S3 to be processed. It returns the list of input file with fileName and fileId.", "operationId": "getInputFiles", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "The X-Request-Id header is optional but incredibly useful for developers. It serves as a unique identifier for requests within our system. When you encounter any problems with your requests, providing us with the X-Request-Id will enable us to pinpoint the specific request in question without the need for extensive manual searching. This means faster and more efficient troubleshooting. The maximum allowed length is 38 characters.", "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174006" } ], "responses": { "200": { "description": "List Uploaded Files getting Successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListInputFilesResponse" }, "examples": { "example": { "value": { "results": [ { "fileId": "d94d4639-2708-49b6-831c-5e861ed4607d", "fileName": "TEST_DATA_1" }, { "fileId": "edfdf995-3ff4-426a-9fda-09687edd0a2e", "fileName": "TEST_DATA_2" }, { "fileId": "badddddf-0006-4de8-a38d-4e0772fbda8e", "fileName": "TEST_DATA_3" }, { "fileId": "16bb27b6-9f71-4bf2-8c34-19d4a7b6a035", "fileName": "TEST_DATA_4" }, { "fileId": "9b993962-082d-4150-a24a-9a5d472e7631", "fileName": "TEST_DATA_5" } ] } } } } } }, "401": { "description": "Unauthorized: Invalid token for Get Input Files API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_TOKEN", "errorMessage": "Unauthorized (DIS-1001)" } ] } } } } } }, "403": { "description": "Forbidden for Get Input Files API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "FORBIDDEN", "errorMessage": "You do not have permission to access this API (DIS-1002)" } ] } } } } } }, "429": { "description": "Too many requests for Get Input Files API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "TOO_MANY_REQUESTS", "errorMessage": "Rate limit exceeded (DIS-1005)" } ] } } } } } }, "500": { "description": "Internal Server Error for Get Input Files API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INTERNAL_ERROR", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-1003)" } ] } } } } } } }, "deprecated": true, "security": [ { "bearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/files/upload-url": { "post": { "tags": [ "Bulk Geo Addressing" ], "summary": "Generates url for uploading the file", "description": "This API generates url for uploading the file to the S3 bucket. It takes the file name and returns the file id and pre-signed uploading URL which can be used to upload the file to the S3 bucket.", "operationId": "generateUrl", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "The X-Request-Id header is optional but incredibly useful for developers. It serves as a unique identifier for requests within our system. When you encounter any problems with your requests, providing us with the X-Request-Id will enable us to pinpoint the specific request in question without the need for extensive manual searching. This means faster and more efficient troubleshooting. The maximum allowed length is 38 characters.", "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174006" } ], "requestBody": { "description": "This API generates url for uploading", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadUrlRequest" }, "examples": { "example": { "value": { "fileName": "test" } } } } }, "required": true }, "responses": { "200": { "description": "File upload url generated Successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadUrlResponse" }, "examples": { "example": { "value": { "fileId": "8d907c8c-5b63-417f-b69f-2d33dbdd2fcd", "url": "https://us-east-1-bulk-api.s3.us-east-1.amazonaws.com/test/test_user_1%40precisely.com/input/test_new%3A%3A8d907c8c-5b63-417f-b69f-2d33dbdd2fcd%0A?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20230921T091012Z&X-Amz-SignedHeaders=content-type%3Bhost&X-Amz-Expires=599&X-Amz-Credential=AKIA3MFZWFWEOJGTLJF2%2F20230921%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=978f32359ac7f650fbabe84a77622be11822e9e40cb0841696d947e33a773e86", "message": "This download URL will be valid for the next 10 mins." } } } } } }, "400": { "description": "Invalid request for Generate URL API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_CLIENT_INPUT", "errorMessage": "Request is not valid (DIS-LI-1018)" } ] } } } } } }, "401": { "description": "Unauthorized: Invalid token for Generate URL API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_TOKEN", "errorMessage": "Unauthorized (DIS-1001)" } ] } } } } } }, "403": { "description": "Forbidden for Generate URL API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "FORBIDDEN", "errorMessage": "You do not have permission to access this API (DIS-1002)" } ] } } } } } }, "429": { "description": "Too many requests for Generate URL API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "TOO_MANY_REQUESTS", "errorMessage": "Rate limit exceeded (DIS-1005)" } ] } } } } } }, "500": { "description": "Internal Server Error for Generate URL API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INTERNAL_ERROR", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-1003)" } ] } } } } } } }, "deprecated": true, "security": [ { "bearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/files/{fileId}": { "delete": { "tags": [ "Bulk Geo Addressing" ], "summary": "Deletes file which are available on S3 to be processed", "description": "This API deletes a file which are available on S3 to be processed. It takes the file id and returns the status of the delete operation.", "operationId": "deleteInputFile", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "The X-Request-Id header is optional but incredibly useful for developers. It serves as a unique identifier for requests within our system. When you encounter any problems with your requests, providing us with the X-Request-Id will enable us to pinpoint the specific request in question without the need for extensive manual searching. This means faster and more efficient troubleshooting. The maximum allowed length is 38 characters.", "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174006" }, { "name": "fileId", "in": "path", "description": "Use the file id that was returned while creating upload url. File id will be used for deleting that particular file from S3", "required": true, "schema": { "type": "string" }, "example": "8d907c8c-5b63-417f-b69f-2d33dbdd2fcd" } ], "responses": { "200": { "description": "File Deleted Successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteFileResponse" }, "examples": { "example": { "value": { "status": "SUCCESS", "message": "File Deleted Successfully" } } } } } }, "400": { "description": "Invalid request for Delete Input File API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_REQUEST", "errorMessage": "Invalid File Id (DIS-LI-1052)" } ] } } } } } }, "401": { "description": "Unauthorized: Invalid token for Delete Input File API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_TOKEN", "errorMessage": "Unauthorized (DIS-1001)" } ] } } } } } }, "403": { "description": "Forbidden for Delete Input File API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "FORBIDDEN", "errorMessage": "You do not have permission to access this API (DIS-1002)" } ] } } } } } }, "429": { "description": "Too many requests for Delete Input File API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "TOO_MANY_REQUESTS", "errorMessage": "Rate limit exceeded (DIS-1005)" } ] } } } } } }, "500": { "description": "Internal Server Error for Delete Input File API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INTERNAL_ERROR", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-1003)" } ] } } } } } } }, "deprecated": true, "security": [ { "bearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v2/bulk-geocode": { "post": { "tags": [ "Bulk Geo Addressing" ], "summary": "Bulk geocodes the addresses file", "description": "This V2 API geocodes the addresses file. It takes file id corresponding to uploaded file and returns the url to check the status of geocoding job.", "operationId": "bulkGeocodeV2", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "The X-Request-Id header is optional but incredibly useful for developers. It serves as a unique identifier for requests within our system. When you encounter any problems with your requests, providing us with the X-Request-Id will enable us to pinpoint the specific request in question without the need for extensive manual searching. This means faster and more efficient troubleshooting. The maximum allowed length is 38 characters.", "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174005" }, { "name": "X-CASS-FLOW", "in": "header", "description": "The X-CASS-FLOW header is optional and used for the identification of cass flow.For normal flow it can be empty or null ,but for cass flow we can have one of the 2 values: with_report,no_report", "schema": { "type": "string" }, "example": " " } ], "requestBody": { "description": "This API geocodes the addresses file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkGeocodeRequest" }, "examples": { "example": { "value": { "fileId": "8d907c8c-5b63-417f-b69f-2d33dbdd2fcd" } }, "withReportDetails": { "value": { "fileId": "8d907c8c-5b63-417f-b69f-2d33dbdd2fcd", "reportDetails": { "listProcessorName": "Precisely Software Inc.", "listNameId": "file_1", "totalList": "1", "mailingAddress": "123 Main St, New York, NY 10001 USA" } } }, "withDelimiter": { "value": { "fileId": "8d907c8c-5b63-417f-b69f-2d33dbdd2fcd", "delimiter": "|" } }, "withDelimiterAndPreference": { "value": { "fileId": "8d907c8c-5b63-417f-b69f-2d33dbdd2fcd", "delimiter": "|", "preferences": { "maxResults": 1, "returnAllInfo": true, "factoryDescription": { "label": "", "featureSpecific": {} }, "clientLocale": "en_US", "clientCoordSysName": "", "distance": { "value": 150, "distanceUnit": "METER" }, "streetOffset": { "value": 7, "distanceUnit": "METER" }, "cornerOffset": { "value": 7, "distanceUnit": "METER" }, "fallbackToGeographic": true, "fallbackToPostal": true, "matchMode": "", "returnOfAdditionalFields": [], "originXY": [], "customPreferences": {} } } } } } }, "required": true }, "responses": { "202": { "description": "Bulk Geocode Job Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkGeocodeResponse" }, "examples": { "example": { "value": { "statusUrl": "https://api.cloud.precisely.com/v1/bulk/jobs/180c0892-affc-4f7a-b1c3-d5e965a6eefb" } } } } } }, "400": { "description": "Invalid request for Bulk Geocode API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_REQUEST", "errorMessage": "Invalid File Id (DIS-LI-1052)" } ] } } } } } }, "401": { "description": "Unauthorized: Invalid token for Bulk Geocode API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_TOKEN", "errorMessage": "Unauthorized (DIS-1001)" } ] } } } } } }, "403": { "description": "Forbidden for Bulk Geocode API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "FORBIDDEN", "errorMessage": "You do not have permission to access this API (DIS-1002)" } ] } } } } } }, "429": { "description": "Too many requests for Bulk Geocode API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "TOO_MANY_REQUESTS", "errorMessage": "Rate limit exceeded (DIS-1005)" } ] } } } } } }, "500": { "description": "Internal Server Error for Bulk Geocode API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INTERNAL_ERROR", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-1003)" } ] } } } } } } }, "security": [ { "bearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v2/bulk-verify": { "post": { "tags": [ "Bulk Geo Addressing" ], "summary": "Performs address verification and standardization of the addresses file", "description": "This V2 API performs address verification and standardization of the addresses file. It takes file id corresponding to uploaded file and returns the url to check the status of address verification job.", "operationId": "bulkVerifyV2", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "The X-Request-Id header is optional but incredibly useful for developers. It serves as a unique identifier for requests within our system. When you encounter any problems with your requests, providing us with the X-Request-Id will enable us to pinpoint the specific request in question without the need for extensive manual searching. This means faster and more efficient troubleshooting. The maximum allowed length is 38 characters.", "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174003" }, { "name": "X-CASS-FLOW", "in": "header", "description": "The X-CASS-FLOW header is optional and used for the identification of cass flow.For normal flow it can be empty or null ,but for cass flow we can have one of the 2 values: with_report,no_report", "schema": { "type": "string" }, "example": " " } ], "requestBody": { "description": "This API performs address verification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkGeocodeRequest" }, "examples": { "example": { "value": { "fileId": "8d907c8c-5b63-417f-b69f-2d33dbdd2fcd" } }, "withReportDetails": { "value": { "fileId": "8d907c8c-5b63-417f-b69f-2d33dbdd2fcd", "reportDetails": { "listProcessorName": "Precisely Software Inc.", "listNameId": "file_1", "totalList": "1", "mailingAddress": "123 Main St, New York, NY 10001 USA" } } }, "withDelimiter": { "value": { "fileId": "8d907c8c-5b63-417f-b69f-2d33dbdd2fcd", "delimiter": "|" } }, "withDelimiterAndPreference": { "value": { "fileId": "8d907c8c-5b63-417f-b69f-2d33dbdd2fcd", "delimiter": "|", "preferences": { "maxResults": 1, "returnAllInfo": true, "factoryDescription": { "label": "", "featureSpecific": {} }, "clientLocale": "en_US", "clientCoordSysName": "", "distance": { "value": 150, "distanceUnit": "METER" }, "streetOffset": { "value": 7, "distanceUnit": "METER" }, "cornerOffset": { "value": 7, "distanceUnit": "METER" }, "fallbackToGeographic": true, "fallbackToPostal": true, "matchMode": "", "returnOfAdditionalFields": [], "originXY": [], "customPreferences": {} } } } } } }, "required": true }, "responses": { "202": { "description": "Bulk Verify Job Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkGeocodeResponse" }, "examples": { "example": { "value": { "statusUrl": "https://api.cloud.precisely.com/v1/bulk/jobs/180c0892-affc-4f7a-b1c3-d5e965a6eefb" } } } } } }, "400": { "description": "Invalid request for Bulk Verify API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_REQUEST", "errorMessage": "Invalid File Id (DIS-LI-1052)" } ] } } } } } }, "401": { "description": "Unauthorized: Invalid token for Bulk Verify API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_TOKEN", "errorMessage": "Unauthorized (DIS-1001)" } ] } } } } } }, "403": { "description": "Forbidden for Bulk Verify API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "FORBIDDEN", "errorMessage": "You do not have permission to access this API (DIS-1002)" } ] } } } } } }, "429": { "description": "Too many requests for Bulk Verify API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "TOO_MANY_REQUESTS", "errorMessage": "Rate limit exceeded (DIS-1005)" } ] } } } } } }, "500": { "description": "Internal Server Error for Bulk Verify API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INTERNAL_ERROR", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-1003)" } ] } } } } } } }, "security": [ { "bearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v2/bulk/jobs": { "get": { "tags": [ "Bulk Geo Addressing" ], "summary": "This V2 version provide list of jobs that are in scheduled or running state for particular user", "description": "This API returns a list of bulk geocode/verify jobs for the authenticated user.\nYou can optionally filter jobs by status (scheduled, running, or all).\nOnly the 'status' query parameter is accepted; any other query parameters will result in a 400 Bad Request error.", "operationId": "listJobsV2", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "The X-Request-Id header is optional but incredibly useful for developers. It serves as a unique identifier for requests within our system. When you encounter any problems with your requests, providing us with the X-Request-Id will enable us to pinpoint the specific request in question without the need for extensive manual searching. This means faster and more efficient troubleshooting.", "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174004" }, { "name": "status", "in": "query", "description": "Filter jobs by status. Allowed values: 'scheduled', 'running', or 'all'. If not provided, returns all jobs.", "required": false, "schema": { "type": "string", "enum": [ "scheduled", "running", "all" ] }, "example": "scheduled" } ], "responses": { "200": { "description": "List of scheduled/running jobs returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueuedJobsResponse" }, "examples": { "example": { "value": { "jobs": [ { "jobId": "bd80fe36-d7f4-4bc8-b1a2-4d25c04f842e", "emailId": "sample_user@precisely.com", "fileId": "bb1cef64-1fb1-4433-a440-e62252cd2fe8", "fileName": "SampleFile", "status": "SCHEDULED", "submittedAt": "2025-11-03T09:39:17.128Z" }, { "jobId": "617c3dbb-4c56-4ec7-a9cb-962450a3022e", "emailId": "sample_user@precisely.com", "fileId": "bb1cef64-1fb1-4433-a440-e62252cd2fe8", "fileName": "SampleFile", "status": "RUNNING", "submittedAt": "2025-11-03T09:39:10.849Z" } ] } } } } } }, "400": { "description": "Bad Request - Invalid query parameters. Only 'status' parameter is allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_CLIENT_INPUT", "errorMessage": "Request is not valid (DIS-LI-1018)" } ] } } } } } }, "401": { "description": "Unauthorized: Invalid token for List Bulk Job API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_TOKEN", "errorMessage": "Unauthorized (DIS-1001)" } ] } } } } } }, "403": { "description": "Forbidden for List Bulk Job API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "FORBIDDEN", "errorMessage": "You do not have permission to access this API (DIS-1002)" } ] } } } } } }, "429": { "description": "Too many requests for List Bulk Job API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "TOO_MANY_REQUESTS", "errorMessage": "Rate limit exceeded (DIS-1005)" } ] } } } } } }, "500": { "description": "Internal Server Error for List Bulk Job API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INTERNAL_ERROR", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-1003)" } ] } } } } } } }, "security": [ { "bearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v2/bulk/jobs/{jobId}": { "get": { "tags": [ "Bulk Geo Addressing" ], "summary": "This V2 version checks status of requested job of bulk geocode/verify", "description": "This V2 version API checks status of requested job of bulk geocode/verify. It takes the job id provided when we submit bulk geocode/verify job and returns the status of the job. Once the job is completed it returns download url of output file along with status.", "operationId": "getStatusV2", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "The X-Request-Id header is optional but incredibly useful for developers. It serves as a unique identifier for requests within our system. When you encounter any problems with your requests, providing us with the X-Request-Id will enable us to pinpoint the specific request in question without the need for extensive manual searching. This means faster and more efficient troubleshooting.", "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174004" }, { "name": "jobId", "in": "path", "description": "job id of bulk geocode or verify", "required": true, "schema": { "type": "string" }, "example": "8d907c8c-5b63-417f-b69f-2d33dbdd2fcd" } ], "responses": { "200": { "description": "Status got successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStatusResponse" }, "examples": { "example": { "value": { "status": "COMPLETED", "downloadUrl": "https://us-east-1-bulk-api.s3.us-east-1.amazonaws.com/test/test_user_1%40precisely.com/output/91ff044f-cc42-4c8a-a781-43fdc4a14963/test_file%3A%3A16bb27b6-9f71-4bf2-8c34-19d4a7b6a035.csv?X-Amz-Security-Token=IQoJb3JpZ2luX2VjEAMaCXVzLWVhc3QtMiJHMEUCIQDfJzxD1buoQg3Fp0jUfnjrPQRzA0bmD6O%2FeN%2BZAQc2tAIgRttKfyWQy8THMc0BrfwsuSNDMTBFS20oett2EGnnyQEqjQUI7f%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FARADGgw1MDg3NDc3ODk4NzQiDGdtz11Dx2e%2FouDkdirhBEYLDfQRUlSbYElOfuxnfKudb5BVA284Eb34UNgCRab13ectiAyoyYUIX74%2BTi7hnzDvMnarybgJza55905L2hXg5AHwdFqQPNjXyawhaikvluV3q%2BHyIP2vTE%2FUXMRFEiCmIs5HXAz99atDghpZPVjV7cGNMRAKN8SFoEtaDLJ%2FUvA1EUskqL0CsZfBybR7lSOszVfQ6CypQ1TVAMk9t9jpj%2BLwUWLIxk7usggoWzQdvMV%2FjcvDNZkmk0UoveM5CFHGt98mru2l%2FqW96nV8ld3IOyxqMx1f8c3Upcdbi416Ln8CjphttbVSNUONluzdVtTndf87zEC5O%2B810x%2FDLqDAmOZ5Q%2Bgs3YCtpxwhhw%2FjwVUv318O0yqQVZs0zL0ZuJOWAZqIMKIzRhiEJjihRkbzMqWtPQEG%2BXzgWMPficJQRqjs9i7WnmTjrZ0aaOXNqZ2KrGnj2AjMKtnrmj5FYM6tYq850o%2FzmpWoRtefHf0NxzYTJCswRVz7fG%2FZ%2BbBdT9rO%2FTMDw5QI9U07VkCbeGfc0hFK5Spaee%2F8PTJyDrlESLN0AyTmk3zaEGR6onoysyQxduHKx8HTVJYr2VQcmZM1ltaml9Z7d5hIZQJ6n0FJ5fXwNu0p%2BJSewbDwDImTgNQm7XMbHEpfv%2BZ2lAnA07lyxMJq%2FIjJ5G2%2BaBuFb7%2FR5HtGzq0VmGd0AWe0EtgNlGFgMnAyLlpZBOsl1u6vmB3%2BKw5ID5a7aRbUp4IHdlOBr2BHLu%2BFU9Vl8sUUxo3rfyqsJFnriavWH5aP39Mbm3rDb7dcTDHkMO%2FAqcbo3L9YgTDh0bCoBjqaAXLMcTNBcNiDQ8Scpn%2FidqSQ2u1sfn8jbmp3ERj%2FU4VeIkxlxkpcBYHZ0ujmHu3LDDeD8ze9190Ck9awsVjnKcWc2cf20p6UJ34%2Ff2LvS%2BvnkprNn1sNZAYPC6DbfC%2FUzv6SjN2%2FVCWn1hM6h7WJwjHIcFY0VRF%2BdkHzHFn0d8UvJAHE1yQELUAl8DF0JX60P7ZNbDvJ8hC4gu4%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20230921T115717Z&X-Amz-SignedHeaders=host&X-Amz-Expires=599&X-Amz-Credential=ASIAXM453GYZCWAGCK66%2F20230921%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Signature=f854694713bcc466fe5b358a1b0bff49446b2f4689422405e213d4ab3ef8e4ea", "message": "This download URL will be valid for the next 10 mins." } } } } } }, "400": { "description": "Invalid request for Bulk Job Status API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_REQUEST", "errorMessage": "Invalid Job Id (DIS-LI-1051)" } ] } } } } } }, "401": { "description": "Unauthorized: Invalid token for Bulk Job Status API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_TOKEN", "errorMessage": "Unauthorized (DIS-1001)" } ] } } } } } }, "403": { "description": "Forbidden for Bulk Job Status API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "FORBIDDEN", "errorMessage": "You do not have permission to access this API (DIS-1002)" } ] } } } } } }, "429": { "description": "Too many requests for Bulk Job Status API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "TOO_MANY_REQUESTS", "errorMessage": "Rate limit exceeded (DIS-1005)" } ] } } } } } }, "500": { "description": "Internal Server Error for Bulk Job Status API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INTERNAL_ERROR", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-1003)" } ] } } } } } } }, "security": [ { "bearerAuth": [] }, { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Bulk Geo Addressing" ], "summary": "This V2 version cancels requested job of bulk geocode/verify which is in Scheduled state", "description": "This V2 version API cancels Scheduled state jobs of bulk geocode/verify.", "operationId": "cancelScheduledJobV2", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "The X-Request-Id header is optional but incredibly useful for developers. It serves as a unique identifier for requests within our system. When you encounter any problems with your requests, providing us with the X-Request-Id will enable us to pinpoint the specific request in question without the need for extensive manual searching. This means faster and more efficient troubleshooting.", "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174004" }, { "name": "jobId", "in": "path", "description": "job id of bulk geocode or verify", "required": true, "schema": { "type": "string" }, "example": "8d907c8c-5b63-417f-b69f-2d33dbdd2fcd" } ], "responses": { "200": { "description": "Request received for job cancellation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelJobResult" }, "examples": { "example": { "value": { "jobId": "fdb25e89-30c0-4fdb-b2b8-2c6e24736ad9", "message": "Request received for job cancellation" } } } } } }, "400": { "description": "Invalid JobId for cancellation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "BAD_REQUEST", "errorMessage": "Invalid Job Id (DIS-LI-1051)" } ] } } } } } }, "401": { "description": "Unauthorized: Invalid token for Cancel Bulk Job API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_TOKEN", "errorMessage": "Unauthorized (DIS-1001)" } ] } } } } } }, "403": { "description": "Forbidden for Cancel Bulk Job API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "FORBIDDEN", "errorMessage": "You do not have permission to access this API (DIS-1002)" } ] } } } } } }, "429": { "description": "Too many requests for Cancel Bulk Job API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "TOO_MANY_REQUESTS", "errorMessage": "Rate limit exceeded (DIS-1005)" } ] } } } } } }, "500": { "description": "Internal Server Error for Cancel Bulk Job API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INTERNAL_ERROR", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-1003)" } ] } } } } } } }, "security": [ { "bearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v2/files": { "get": { "tags": [ "Bulk Geo Addressing" ], "summary": "This V2 version gets the list of files which are available on S3 to be processed", "description": "This V2 version API gets the list of files which are available on S3 to be processed. It returns the list of input file with fileName and fileId.", "operationId": "getInputFilesV2", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "The X-Request-Id header is optional but incredibly useful for developers. It serves as a unique identifier for requests within our system. When you encounter any problems with your requests, providing us with the X-Request-Id will enable us to pinpoint the specific request in question without the need for extensive manual searching. This means faster and more efficient troubleshooting. The maximum allowed length is 38 characters.", "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174006" } ], "responses": { "200": { "description": "List Uploaded Files getting Successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListInputFilesResponse" }, "examples": { "example": { "value": { "results": [ { "fileId": "d94d4639-2708-49b6-831c-5e861ed4607d", "fileName": "TEST_DATA_1" }, { "fileId": "edfdf995-3ff4-426a-9fda-09687edd0a2e", "fileName": "TEST_DATA_2" }, { "fileId": "badddddf-0006-4de8-a38d-4e0772fbda8e", "fileName": "TEST_DATA_3" }, { "fileId": "16bb27b6-9f71-4bf2-8c34-19d4a7b6a035", "fileName": "TEST_DATA_4" }, { "fileId": "9b993962-082d-4150-a24a-9a5d472e7631", "fileName": "TEST_DATA_5" } ] } } } } } }, "401": { "description": "Unauthorized: Invalid token for Get Input Files API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_TOKEN", "errorMessage": "Unauthorized (DIS-1001)" } ] } } } } } }, "403": { "description": "Forbidden for Get Input Files API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "FORBIDDEN", "errorMessage": "You do not have permission to access this API (DIS-1002)" } ] } } } } } }, "429": { "description": "Too many requests for Get Input Files API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "TOO_MANY_REQUESTS", "errorMessage": "Rate limit exceeded (DIS-1005)" } ] } } } } } }, "500": { "description": "Internal Server Error for Get Input Files API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INTERNAL_ERROR", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-1003)" } ] } } } } } } }, "security": [ { "bearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v2/files/upload-url": { "post": { "tags": [ "Bulk Geo Addressing" ], "summary": "This V2 version generates url for uploading the file", "description": "This V2 version of API generates url for uploading the file to the S3 bucket. It takes the file name and returns the file id and pre-signed uploading URL which can be used to upload the file to the S3 bucket.", "operationId": "generateUrlV2", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "The X-Request-Id header is optional but incredibly useful for developers. It serves as a unique identifier for requests within our system. When you encounter any problems with your requests, providing us with the X-Request-Id will enable us to pinpoint the specific request in question without the need for extensive manual searching. This means faster and more efficient troubleshooting. The maximum allowed length is 38 characters.", "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174006" } ], "requestBody": { "description": "This API generates url for uploading", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadUrlRequest" }, "examples": { "example": { "value": { "fileName": "test" } } } } }, "required": true }, "responses": { "200": { "description": "File upload url generated Successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadUrlResponse" }, "examples": { "example": { "value": { "fileId": "8d907c8c-5b63-417f-b69f-2d33dbdd2fcd", "url": "https://us-east-1-bulk-api.s3.us-east-1.amazonaws.com/test/test_user_1%40precisely.com/input/test_new%3A%3A8d907c8c-5b63-417f-b69f-2d33dbdd2fcd%0A?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20230921T091012Z&X-Amz-SignedHeaders=content-type%3Bhost&X-Amz-Expires=599&X-Amz-Credential=AKIA3MFZWFWEOJGTLJF2%2F20230921%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=978f32359ac7f650fbabe84a77622be11822e9e40cb0841696d947e33a773e86", "message": "This download URL will be valid for the next 10 mins." } } } } } }, "400": { "description": "Invalid request for Generate URL API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_CLIENT_INPUT", "errorMessage": "Request is not valid (DIS-LI-1018)" } ] } } } } } }, "401": { "description": "Unauthorized: Invalid token for Generate URL API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_TOKEN", "errorMessage": "Unauthorized (DIS-1001)" } ] } } } } } }, "403": { "description": "Forbidden for Generate URL API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "FORBIDDEN", "errorMessage": "You do not have permission to access this API (DIS-1002)" } ] } } } } } }, "429": { "description": "Too many requests for Generate URL API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "TOO_MANY_REQUESTS", "errorMessage": "Rate limit exceeded (DIS-1005)" } ] } } } } } }, "500": { "description": "Internal Server Error for Generate URL API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INTERNAL_ERROR", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-1003)" } ] } } } } } } }, "security": [ { "bearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v2/files/{fileId}": { "delete": { "tags": [ "Bulk Geo Addressing" ], "summary": "This V2 version deletes file which are available on S3 to be processed", "description": "This V2 version API deletes a file which are available on S3 to be processed. It takes the file id and returns the status of the delete operation.", "operationId": "deleteInputFileV2", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "The X-Request-Id header is optional but incredibly useful for developers. It serves as a unique identifier for requests within our system. When you encounter any problems with your requests, providing us with the X-Request-Id will enable us to pinpoint the specific request in question without the need for extensive manual searching. This means faster and more efficient troubleshooting. The maximum allowed length is 38 characters.", "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174006" }, { "name": "fileId", "in": "path", "description": "Use the file id that was returned while creating upload url. File id will be used for deleting that particular file from S3", "required": true, "schema": { "type": "string" }, "example": "8d907c8c-5b63-417f-b69f-2d33dbdd2fcd" } ], "responses": { "200": { "description": "File Deleted Successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteFileResponse" }, "examples": { "example": { "value": { "status": "SUCCESS", "message": "File Deleted Successfully" } } } } } }, "400": { "description": "Invalid request for Delete Input File API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_REQUEST", "errorMessage": "Invalid File Id (DIS-LI-1052)" } ] } } } } } }, "401": { "description": "Unauthorized: Invalid token for Delete Input File API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_TOKEN", "errorMessage": "Unauthorized (DIS-1001)" } ] } } } } } }, "403": { "description": "Forbidden for Delete Input File API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "FORBIDDEN", "errorMessage": "You do not have permission to access this API (DIS-1002)" } ] } } } } } }, "429": { "description": "Too many requests for Delete Input File API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "TOO_MANY_REQUESTS", "errorMessage": "Rate limit exceeded (DIS-1005)" } ] } } } } } }, "500": { "description": "Internal Server Error for Delete Input File API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INTERNAL_ERROR", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-1003)" } ] } } } } } } }, "security": [ { "bearerAuth": [] }, { "ApiKeyAuth": [] } ] } } }, "components": { "schemas": { "BulkGeocodeRequest": { "required": [ "fileId" ], "type": "object", "properties": { "fileId": { "minLength": 1, "type": "string", "description": "file id of the uploaded file to gecode/verify", "example": "8d907c8c-5b63-417f-b69f-2d33dbdd2fcd" }, "reportDetails": { "description": "Details of the report", "allOf": [ { "$ref": "#/components/schemas/ReportDetails" } ] }, "delimiter": { "pattern": "[,;|\t]?", "type": "string", "description": "Delimiter for separating fields in the file. Supported delimiters are pipe(|) comma(,) semi-comma(;) and tab(\\t)", "example": "\\t", "x-pattern-message": "Delimiter must be one of the following: ',', ';', '\t', or '|'" }, "preferences": { "description": "Preferences that will processed with the request", "allOf": [ { "$ref": "#/components/schemas/Preferences" } ] } }, "description": "Bulk geocode request" }, "BulkGeocodeResponse": { "required": [ "statusUrl" ], "type": "object", "properties": { "statusUrl": { "type": "string", "description": "URL for checking the status of the Bulk Geocode or Verify job", "format": "uri", "example": "https://api.cloud.precisely.com/v1/bulk/jobs/180c0892-affc-4f7a-b1c3-d5e965a6eefb" }, "status": { "type": "string", "description": "Status of Job Submission in not accepted", "nullable": true, "example": "REJECTED" }, "message": { "type": "string", "description": "Message of job submission", "nullable": true, "example": "Queue full" } }, "description": "Bulk geocode response" }, "CancelJobResult": { "type": "object", "properties": { "message": { "type": "string", "description": "Readable message about the cancel attempt.", "example": "Request received for job cancellation" }, "jobId": { "type": "string", "description": "The job ID the cancel was attempted for.", "nullable": true, "example": "8d907c8c-5b63-417f-b69f-2d33dbdd2fcd" } }, "description": "Cancel geocode/verify Scheduled job" }, "DeleteFileResponse": { "required": [ "message", "status" ], "type": "object", "properties": { "status": { "type": "string", "description": "Status of file deleted request", "example": "SUCCESS" }, "message": { "type": "string", "description": "File deletion message", "example": "File Deleted Successfully" } }, "description": "Delete file response" }, "Distance": { "type": "object", "properties": { "value": { "type": "number", "description": "Distance of the radius in which to search for a match. Default is 5.", "format": "double", "example": 5 }, "distanceUnit": { "$ref": "#/components/schemas/DistanceUnit" } }, "description": "'distance' displays the defined search radius (default is 5 meters). 'streetOffset' specifies the offset distance from the street segments to use in street-level geocoding. 'cornerOffset' specifies the distance to offset the street end points in street-level matching (default is 7 meters)." }, "DistanceUnit": { "type": "string", "description": "Distance unit", "example": "METER", "enum": [ "FOOT", "METER", "MILE", "KILOMETER" ] }, "ErrorDetail": { "required": [ "errorMessage", "status" ], "type": "object", "properties": { "status": { "type": "string", "description": "Status of the response", "example": "INVALID_REQUEST" }, "errorMessage": { "type": "string", "description": "Error message from the underlying service", "example": "Request is not valid" } }, "description": "Details of Error" }, "ErrorResponse": { "type": "object", "properties": { "errors": { "type": "array", "description": "list of errors", "items": { "$ref": "#/components/schemas/ErrorDetail" } } }, "description": "Error response" }, "FactoryDescription": { "type": "object", "properties": { "label": { "type": "string", "description": "Sets the addressing processor based on the configured data. Labels are case-sensitive and must be lowercase. Default is \"\".", "example": "asd" }, "featureSpecific": { "description": "Ability to map a feature to an address processor, based on specified label.", "example": { "LOOKUP": "ggs" }, "allOf": [ { "properties": { "GEOCODE": { "type": "string" }, "PARSE": { "type": "string" }, "VERIFY": { "type": "string" }, "REVERSE_GEOCODE": { "type": "string" }, "INTERACTIVE": { "type": "string" }, "LOOKUP": { "type": "string" } } } ] } }, "description": "Controls which address processor will process the request." }, "InputFile": { "required": [ "fileId", "fileName" ], "type": "object", "properties": { "fileId": { "minLength": 1, "type": "string", "description": "id of the uploaded file", "example": "8d907c8c-5b63-417f-b69f-2d33dbdd2fcd" }, "fileName": { "minLength": 1, "type": "string", "description": "name of the uploaded file", "example": "test" } }, "description": "Input file" }, "JobStatusResponse": { "required": [ "status" ], "type": "object", "properties": { "status": { "$ref": "#/components/schemas/Status" }, "downloadUrl": { "type": "string", "description": "url for downloading the output file of the Bulk Geocode/Verify", "format": "url", "example": "https://us-east-1-bulk-api.s3.us-east-1.amazonaws.com/test/test_user_1%40precisely.com/output/91ff044f-cc42-4c8a-a781-43fdc4a14963/test_file%3A%3A16bb27b6-9f71-4bf2-8c34-19d4a7b6a035.csv" }, "reportUrl": { "type": "string", "description": "url for downloading the report file of the Bulk Geocode/Verify", "format": "url", "example": "https://us-east-1-bulk-api.s3.us-east-1.amazonaws.com/test/test_user_1%40precisely.com/output/91ff044f-cc42-4c8a-a781-43fdc4a14963/cass3553.csv" }, "message": { "type": "string", "description": "message for the response", "example": "This download URL will be valid for the next 10 mins." }, "error": { "type": "string", "description": "Error message of the Job", "example": "Invalid Job Id (DIS-LI-1051)" } }, "description": "Job status response" }, "ListInputFilesResponse": { "required": [ "results" ], "type": "object", "properties": { "results": { "type": "array", "description": "List of uploaded files", "items": { "$ref": "#/components/schemas/InputFile" } } }, "description": "List input response" }, "Locale": { "title": "Locale", "type": "object", "properties": { "language": { "type": "string", "description": "The ISO 639 language code.", "example": "en" }, "script": { "type": "string", "description": "The ISO 15924 script code.", "example": "Latn" }, "country": { "type": "string", "description": "The ISO 3166 country code.", "example": "US" }, "variant": { "type": "string", "description": "The variant code for the locale.", "example": "POSIX" }, "unicodeLocaleAttributes": { "type": "array", "description": "The Unicode locale attributes.", "example": [ "attribute1", "attribute2" ], "items": { "type": "string" } }, "unicodeLocaleKeys": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The Unicode locale keys.", "example": { "nu": "thai" } }, "extensionKeys": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The extension keys.", "example": { "x": "private-use" } } }, "description": "Represents a locale with language, script, country, and variant information." }, "Preferences": { "type": "object", "properties": { "maxResults": { "type": "integer", "description": "The maximum number of candidates to return. Default = 1.", "format": "int32", "example": 1 }, "returnAllInfo": { "type": "boolean", "description": "Specifies whether to return all available information for each candidate.", "example": true }, "factoryDescription": { "description": "description of address processor to process the request.", "allOf": [ { "$ref": "#/components/schemas/FactoryDescription" } ] }, "customPreferences": { "type": "object", "additionalProperties": { "type": "string" }, "description": "For use against any country dataset, define custom preferences to control additional functionality such as matching criteria, address casing, and enable functionality like DPV and SuiteLink.", "example": { "DATA_OPTION": "PREMIUM" } }, "clientLocale": { "title": "Locale", "description": "Specifies the locale value. For example, specify \"th\" for the Thai language.", "allOf": [ { "$ref": "#/components/schemas/Locale" } ] }, "clientCoordSysName": { "type": "string", "description": "Specifies the coordinate system that you want to convert the geometry to. The format must be the European Petroleum Survey Group (EPSG) code or the SRID code. Default = EPSG:4326.", "example": "EPSG:4326" }, "distance": { "description": "distance the defined search radius (default is 5 meters)..", "allOf": [ { "$ref": "#/components/schemas/Distance" } ] }, "streetOffset": { "description": "streetOffset specifies the offset distance from the street segments to use in street-level geocoding (Default 5 meters).", "allOf": [ { "$ref": "#/components/schemas/Distance" } ] }, "cornerOffset": { "description": "Specifies the distance to offset the street end points in street-level matching (default is 7 meters).", "allOf": [ { "$ref": "#/components/schemas/Distance" } ] }, "fallbackToGeographic": { "type": "boolean", "description": "Specifies whether to attempt to determine a geographic centroid when an address-level geocode cannot be determined. Optional.", "example": false }, "fallbackToPostal": { "type": "boolean", "description": "Specifies whether to attempt to determine a post code centroid when an address-level geocode cannot be determined. Optional.", "example": false }, "matchMode": { "type": "string", "description": "Match modes determine the leniency used to make a match between the input address and the reference data.", "example": "EXACT" }, "originXY": { "type": "array", "description": "XY coordinates of the origin address.", "example": [ 0, 0 ], "items": { "type": "number", "format": "double" } }, "returnOfAdditionalFields": { "type": "array", "description": "This lets the user control which additional fields they want to have returned if they do not want to return all info.", "example": [ "RESULT_CODE", "PRECISION_CODE" ], "items": { "type": "string" } } }, "description": "Preferences that will processed with the request" }, "QueuedJobView": { "type": "object", "properties": { "jobId": { "type": "string", "description": "Unique job identifier", "example": "XX-1" }, "emailId": { "type": "string", "description": "Owner's email for the job", "example": "user@example.com" }, "fileId": { "type": "string", "description": "Input file identifier", "example": "file-1" }, "fileName": { "type": "string", "description": "Original file name", "example": "name.csv" }, "status": { "type": "string", "description": "Current status of the job", "example": "SCHEDULED" }, "submittedAt": { "type": "string", "description": "Time when job was submitted", "format": "EPOCH", "example": "2025-11-03T09:39:17.128Z" } }, "description": "Details of a job in Scheduled or Running state" }, "QueuedJobsResponse": { "type": "object", "properties": { "jobs": { "type": "array", "description": "List of Jobs with running/scheduled status", "items": { "$ref": "#/components/schemas/QueuedJobView" } } }, "description": "List of Jobs with running/scheduled status" }, "ReportDetails": { "type": "object", "properties": { "listProcessorName": { "type": "string", "description": "Name of the company", "example": "Precisely Software Inc." }, "listNameId": { "type": "string", "description": "Name of the processed file", "example": "Q00362LQ" }, "totalList": { "type": "string", "description": "Total number of lists", "example": "1" }, "mailingAddress": { "type": "string", "description": "Company mailing address", "example": "123 Main St, New York, NY 10001 USA" }, "postNumber": { "type": "string", "description": "Seven-digit POST contract number", "example": "A01 331" } }, "description": "Details for the Report" }, "Status": { "type": "string", "description": "status of the job", "example": "RUNNING", "enum": [ "SCHEDULED", "RUNNING", "COMPLETED", "FAILED", "CANCELED", "REJECTED" ] }, "UploadUrlRequest": { "required": [ "fileName" ], "type": "object", "properties": { "fileName": { "minLength": 1, "pattern": "([A-Za-z])([\\w]*)", "type": "string", "description": "Name of the file to upload", "example": "test.csv" } }, "description": "Upload url request" }, "UploadUrlResponse": { "required": [ "fileId", "message", "url" ], "type": "object", "properties": { "fileId": { "type": "string", "description": "file Id for uploading file", "example": "8d907c8c-5b63-417f-b69f-2d33dbdd2fcd" }, "url": { "type": "string", "description": "pre signed url for uploading the file on S3", "format": "url", "example": "https://us-east-1-test.s3.us-east-1.amazonaws.com/test/test_user_1%40precisely.com/input/test_new%3A%3A8d907c8c-5b63-417f-b69f-2d33dbdd2fcd%0A" }, "message": { "type": "string", "description": "message for the response", "example": "This download URL will be valid for the next 10 mins." } }, "description": "Upload url response" } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "description": "Pass the value in the following format: Apikey .", "name": "Authorization", "in": "header" }, "bearerAuth": { "type": "http", "description": "Pass the value as JWT Bearer Token.", "scheme": "bearer" } } } }