1. Guides
Useme API docs
v1.0
  • v2.0
  • v1.0
  • Guides
    • API 1.0 Deprecation
    • Introduction
    • Getting Started
    • Creating Contractors
    • Creating Deals
    • Retrieving Deal Details
  • Reference
    • Categories
      • List categories
    • Contractors
      • Create a new contractor
    • Deals
      • Create a new deal
      • Retrieve deal details
      • Upload a file for a deal
  • Schemas
    • Schemas
      • ContractorRequest
      • DealDetailsResponse
      • DealRequest
      • GetDealStageData
      • MainCategory
      • WorkFileRequest
    • APIDealBilling
    • BadRequestResponse
    • ConflictResponse
    • APIDealContractorPayment
    • Contractor
    • APIDealEmployerPayment
    • ContractorData
    • APIRetrieveDealResponse
    • CountryCodeEnum
    • DealCreateSuccessResponse
    • Deal
    • DealStageData
    • ErrorResponse
    • FileUploadData
    • FileUploadResponse
    • SubCategory
    • SuccessResponse
    • ValidationErrorResponse
    • RetrieveDealNotFoundResponse
    • RetrieveDealServerErrorResponse
    • RetrieveDealSuccessResponse
    • StatusEnum
    • WorkFile
  1. Guides

API 1.0 Deprecation

API 1.0 is deprecated and should not be used for new integrations. It remains available temporarily to allow existing integrations to migrate to API 2.0.
API 2.0 is the actively supported version and should be used for all new development.
API 1.0 will be retired after the migration period. Existing integrations should move to API 2.0 as soon as possible to avoid service interruption. The retirement date will be communicated separately.

Why is API 1.0 being deprecated?#

API 2.0 introduces a simpler settlement process and reduces the amount of contractor data that employers need to handle.
In API 1.0, employers are responsible for creating contractors, creating deals, and uploading work files through separate API operations. API 2.0 transfers the contractor-facing parts of this process to Useme.
The employer now initiates and tracks the deal through the API, while the contractor completes their profile and provides any required work files directly in Useme.

Migrating to API 2.0#

API 2.0 changes the integration workflow and is not backward compatible with API 1.0. Updating the version number in existing URLs is not sufficient.
When planning the migration, account for the following changes:
a separate contractor creation step is no longer required;
the contractor is identified by email during deal creation;
personal, tax, and payout information is provided by the contractor in Useme;
work files are no longer uploaded through the API;
deals are tracked using the identifier returned by API 2.0;
request and response formats differ from API 1.0.
Review the API 2.0 guides and endpoint reference before updating your integration.

Recommended migration approach#

1.
Obtain access to API 2.0 in the sandbox environment.
2.
Recreate the complete deal workflow using API 2.0.
3.
Update how contractor onboarding and work files are handled.
4.
Update the identifiers and deal statuses stored by your system.
5.
Verify error handling and synchronization of deal states.
6.
Complete end-to-end testing in the sandbox environment.
7.
Switch the production integration to API 2.0.
Do not mix steps from API 1.0 and API 2.0 within a single deal workflow.

Existing API 1.0 integrations#

Existing integrations may continue using API 1.0 during the migration period. However, new functionality will be developed for API 2.0.
If you need assistance with migration or access to API 2.0, contact the Useme support team.
Modified at 2026-07-27 13:00:02
Next
Introduction
Built with