--- title: "Create Instruction" url: "https://developer.pexa.co.uk/apis/instruction-v1-v1/versions/861f183b-600d-4bbf-9762-abebcbf9b5ac/operations/createInstruction" --- > Full API specification: https://developer.pexa.co.uk/apis/instruction-v1-v1/versions/861f183b-600d-4bbf-9762-abebcbf9b5ac.md # Create Instruction `POST` `/partner/api/platformconnect/v1/instructions` Operation ID: `createInstruction` This endpoint enables a lender to create a new case instruction with either the panel management firm or the allocated law firm. ## Header parameters - `X-Request-Correlation-Id` (string, optional) - The unique identifier for the request ## Request body (required) Content types: `application/json` ## Responses - `201` - CREATED - `400` - BAD REQUEST - `401` - UNAUTHORISED - `403` - FORBIDDEN - `409` - CONFLICT - `500` - INTERNAL SERVER ERROR - `503` - SERVICE UNAVAILABLE ## OpenAPI definition ```yaml openapi: 3.0.1 info: title: Lender Instruction version: v1 servers: - url: https://api.pexa.co.uk description: API Gateway URL paths: /partner/api/platformconnect/v1/instructions: post: tags: - InstructionV1 summary: Create Instruction description: This endpoint enables a lender to create a new case instruction with either the panel management firm or the allocated law firm. operationId: createInstruction security: - oauth2: - x-api:create:instructions parameters: - name: X-Request-Correlation-Id in: header description: The unique identifier for the request required: false schema: type: string requestBody: content: application/json: schema: type: object required: - routingConfig - instructionsDetails properties: routingConfig: type: object description: Information used to determine where to route the instruction properties: assignedPanelManager: type: string pattern: ^(SMOOVE)$ description: | The assigned panel manager Allowed Values: [ `SMOOVE`] assignedPanelLawFirm: type: string maxLength: 50 description: Panel reference held by the Panel Manager for the law firm assignedLawFirm: type: string pattern: ^(OPTIMA)$ description: | The actual law firm name Allowed Values: [ `OPTIMA` ] pexaEligible: type: boolean description: Indicates if the funds should be settled by PEXA instructionsDetails: type: object required: - reference - property - parties - transactionType properties: reference: type: string minLength: 1 maxLength: 40 description: The lender held reference for the mortgage application loanAmount: type: number minimum: 1 format: double description: The amount of the loan transactionType: type: string pattern: ^(PURCHASE|REMORTGAGE)$ description: | Allowed values: [ `PURCHASE`, `REMORTGAGE` ] serviceLevel: type: string pattern: ^(STANDARD|PREMIER)$ description: > Level of service required for this instruction Allowed values: [ `STANDARD`, `PREMIER` ] lender: type: object properties: accountNumber: type: string description: The lender account number sortCode: type: string description: The lender sort code property: type: object required: - address - jurisdiction properties: jurisdiction: type: string pattern: ^(ENGLAND_WALES|SCOTLAND|NORTHERN_IRELAND)$ description: > The jurisdiction of the property (REQUIRED field as of v1.1.0) Allowed values: [`ENGLAND_WALES`, `SCOTLAND`, `NORTHERN_IRELAND`] country: type: string pattern: ^(ENGLAND|WALES|SCOTLAND|NORTHERN_IRELAND)$ description: > The country where the property is located Allowed values: [`ENGLAND`, `WALES`, `SCOTLAND`, `NORTHERN_IRELAND`] address: type: object required: - postcode properties: flat: type: string description: Flat/apartment number name: type: string description: Building name number: type: string description: House/building number street: type: string description: Street name town: type: string description: Town/city postcode: maxLength: 8 minLength: 6 type: string example: M16 0RA pattern: ^(([Gg][Ii][Rr] 0[Aa]{2})|((([A-Za-z][0-9]{1,2})|(([A-Za-z][A-Ha-hJ-Yj-y][0-9]{1,2})|(([A-Za-z][0-9][A-Za-z])|([A-Za-z][A-Ha-hJ-Yj-y][0-9][A-Za-z]?))))\s[0-9][A-Za-z]{2}))$ locality: type: string description: Locality county: type: string description: County name unencumbered: type: boolean description: Indicates if the property is unencumbered tenure: type: string pattern: ^(FREEHOLD|LEASEHOLD)$ description: > The tenure of the property Allowed values: [ `FREEHOLD`, `LEASEHOLD`] occupancyType: type: string pattern: ^(OWNER_OCCUPIED|BUY_TO_LET|SECOND_HOME|HOLIDAY_LET)$ description: > Type of occupancy for the property Allowed values: [ `OWNER_OCCUPIED`, `BUY_TO_LET`, `SECOND_HOME`, `HOLIDAY_LET` ] newBuild: type: boolean description: Indicates if the property is a new build parties: type: array description: Information about the applicants, introducer, and outgoing lender (up to 4 applicants plus introducer and outgoing lender as needed) items: oneOf: - type: object required: - type - partyDetails allOf: - type: object discriminator: propertyName: type mapping: INDIVIDUAL: "#/components/schemas/IndividualParty" ORGANISATION: "#/components/schemas/OrganisationParty" properties: role: type: string pattern: ^(BORROWER|BUYER|INTRODUCER|OUTGOING_LENDER)$ description: > Allowed Values: [`BORROWER`, `BUYER`, `INTRODUCER`, `OUTGOING_LENDER`] addresses: type: array items: type: object required: - type - details properties: type: type: string pattern: ^(REGISTERED_ADDRESS)$ description: > Allowed values: [ `REGISTERED_ADDRESS`] example: REGISTERED_ADDRESS details: type: object required: - postcode properties: name: maxLength: 50 minLength: 0 type: string description: Building name example: 1 The House number: maxLength: 4 minLength: 0 type: string description: House/building number example: 123a flat: maxLength: 30 minLength: 0 type: string description: Flat/apartment number example: Flat 32 street: maxLength: 60 minLength: 0 type: string description: Street name example: Huddersfield town: maxLength: 30 minLength: 0 type: string description: Town/city example: West Yorkshire county: type: string description: County name (required for OCE verification) example: Greater London postcode: maxLength: 8 minLength: 6 type: string example: M16 0RA pattern: ^(([Gg][Ii][Rr] 0[Aa]{2})|((([A-Za-z][0-9]{1,2})|(([A-Za-z][A-Ha-hJ-Yj-y][0-9]{1,2})|(([A-Za-z][0-9][A-Za-z])|([A-Za-z][A-Ha-hJ-Yj-y][0-9][A-Za-z]?))))\s[0-9][A-Za-z]{2}))$ locality: type: string description: Locality example: Kensington description: Address information for the party required: - role properties: type: type: string pattern: ^(INDIVIDUAL)$ description: | Allowed Values: [`INDIVIDUAL`] partyDetails: type: object properties: forenames: type: string maxLength: 90 minLength: 1 pattern: ^[A-Za-z][A-Za-z\- ']*$ description: Forename is required for Individual BORROWER and BUYER parties example: James Thomas surname: type: string maxLength: 50 minLength: 1 pattern: ^[A-Za-z][A-Za-z\ - ']*$ description: Surname is required for Individual BORROWER and BUYER parties example: Smith title: type: string description: Title (e.g., "Mr", "Mrs", "Dr") dateOfBirth: type: string format: date description: Date of birth (YYYY-MM-DD) mobile: type: string pattern: ^(\+?\d{1,4}[- ]?)?[\d\s-]{4,20}$ description: Mobile phone number minLength: 4 maxLength: 20 phone: type: string pattern: ^(\+?\d{1,4}[- ]?)?[\d\s-]{4,20}$ description: Home landline phone number minLength: 4 maxLength: 20 email: type: string maxLength: 100 pattern: ^$|(?:[A-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[A-z0-9!#$%&'*+/=?^_`{|}~-]+)*|"(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[A-z0-9](?:[A-z0-9-]*[A-z0-9])?\.)+[A-z0-9](?:[A-z0-9-]*[A-z0-9])?|\[(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?|[A-z0-9-]*[A-z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5A\x53-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\]) example: john.smith@lawfirm.com description: Email address fcaNumber: type: string description: FCA registration number is required only for Individual INTRODUCER party example: "123456" organisationName: type: string maxLength: 160 minLength: 1 pattern: ^[a-zA-ZÀ-ÖØ-öø-ſĀ-ıĴ-ľŁ-ʼnŊ-ŏŐ-őŒ-žǼǺǾẀẂẄỲǽǻǿẁẃẅỳ\d&@£$€¥#'''(){}<>!«»"""\[\]?*=%+\s.,:\/;\\-]+$ description: Organization name example: Mortgage Broker Corp Ltd - type: object required: - type - partyDetails allOf: - type: object discriminator: propertyName: type mapping: INDIVIDUAL: "#/components/schemas/IndividualParty" ORGANISATION: "#/components/schemas/OrganisationParty" properties: role: type: string pattern: ^(BORROWER|BUYER|INTRODUCER|OUTGOING_LENDER)$ description: > Allowed Values: [`BORROWER`, `BUYER`, `INTRODUCER`, `OUTGOING_LENDER`] addresses: type: array items: type: object required: - type - details properties: type: type: string pattern: ^(REGISTERED_ADDRESS)$ description: > Allowed values: [ `REGISTERED_ADDRESS`] example: REGISTERED_ADDRESS details: type: object required: - postcode properties: name: maxLength: 50 minLength: 0 type: string description: Building name example: 1 The House number: maxLength: 4 minLength: 0 type: string description: House/building number example: 123a flat: maxLength: 30 minLength: 0 type: string description: Flat/apartment number example: Flat 32 street: maxLength: 60 minLength: 0 type: string description: Street name example: Huddersfield town: maxLength: 30 minLength: 0 type: string description: Town/city example: West Yorkshire county: type: string description: County name (required for OCE verification) example: Greater London postcode: maxLength: 8 minLength: 6 type: string example: M16 0RA pattern: ^(([Gg][Ii][Rr] 0[Aa]{2})|((([A-Za-z][0-9]{1,2})|(([A-Za-z][A-Ha-hJ-Yj-y][0-9]{1,2})|(([A-Za-z][0-9][A-Za-z])|([A-Za-z][A-Ha-hJ-Yj-y][0-9][A-Za-z]?))))\s[0-9][A-Za-z]{2}))$ locality: type: string description: Locality example: Kensington description: Address information for the party required: - role properties: type: type: string pattern: ^(ORGANISATION)$ description: | Allowed Values: [`ORGANISATION`] partyDetails: type: object required: - organisationName properties: organisationName: type: string maxLength: 160 minLength: 1 pattern: ^[a-zA-ZÀ-ÖØ-öø-ſĀ-ıĴ-ľŁ-ʼnŊ-ŏŐ-őŒ-žǼǺǾẀẂẄỲǽǻǿẁẃẅỳ\d&@£$€¥#'''(){}<>!«»"""\[\]?*=%+\s.,:\/;\\-]+$ description: Organization name is required for Organisation BORROWER and BUYER parties example: Smith Ltd registrationNumber: type: string minLength: 6 maxLength: 8 pattern: ^[A-Z0-9]+$ description: Company registration number is required only for Organisation BORROWER, BUYER, OUTGOING_LENDER parties example: "12345678" organisationType: type: string pattern: ^(LIMITED_COMPANY)$ description: > Type of organization is required only only for Organisation BORROWER and BUYER parties Allowed Values: [`LIMITED_COMPANY`] example: LIMITED_COMPANY outgoingLenderAccountNumber: type: string description: Account number with the outgoing lender is required for only Organisation OUTGOING_LENDER party example: "12345678" mortgagePrisoner: type: boolean description: Indicates if this is a mortgage prisoner examples: createInstructionWithPanelManager: summary: Create instruction with panel manager routing value: routingConfig: assignedPanelManager: SMOOVE assignedPanelLawFirm: PANEL123 pexaEligible: true instructionsDetails: reference: LENDER-REF-001 loanAmount: 250000 transactionType: PURCHASE serviceLevel: STANDARD lender: accountNumber: "12345678" sortCode: 12-34-56 property: jurisdiction: ENGLAND_WALES country: ENGLAND address: flat: Flat 2 name: The Manor House number: "123" street: High Street town: London postcode: SW1A 1AA unencumbered: false tenure: FREEHOLD occupancyType: OWNER_OCCUPIED newBuild: false parties: - type: INDIVIDUAL role: BORROWER partyDetails: forenames: John Michael surname: Smith title: Mr dateOfBirth: 1985-06-15 mobile: 7123456789 email: john.smith@email.com addresses: - type: REGISTERED_ADDRESS details: flat: Flat 2 name: The Manor House number: "123" street: High Street town: London postcode: SW1A 1AA mortgagePrisoner: false createInstructionWithLawFirm: summary: Create instruction with law firm routing value: routingConfig: assignedLawFirm: OPTIMA pexaEligible: true instructionsDetails: reference: LENDER-REF-002 loanAmount: 180000 transactionType: REMORTGAGE serviceLevel: PREMIER lender: accountNumber: "87654321" sortCode: 65-43-21 property: jurisdiction: SCOTLAND country: SCOTLAND address: number: "456" street: Castle Street town: Edinburgh postcode: EH1 2NG unencumbered: true tenure: FREEHOLD occupancyType: BUY_TO_LET newBuild: true parties: - type: ORGANISATION role: BORROWER partyDetails: organisationName: Property Investment Ltd registrationNumber: "12345678" organisationType: LIMITED_COMPANY addresses: - type: REGISTERED_ADDRESS details: number: "789" street: Commercial Road town: Glasgow postcode: G1 1AA - type: ORGANISATION role: OUTGOING_LENDER partyDetails: organisationName: Previous Bank Ltd outgoingLenderAccountNumber: "98765432" addresses: - type: REGISTERED_ADDRESS details: name: Banking House number: "100" street: Financial District town: London postcode: EC2A 1AA mortgagePrisoner: true required: true responses: "201": description: CREATED headers: X-API-Version: schema: type: string description: The API version that was used to process the request. X-Request-Correlation-Id: schema: type: string description: The unique identifier for the request content: application/json: schema: type: object required: - instructionId properties: instructionId: type: string format: uuid description: Unique identifier for the created instruction workspaceId: type: string format: uuid description: Unique identifier for the associated PEXA workspace parties: type: array description: Information about the applicants, introducer, and outgoing lender items: oneOf: - type: object required: - type - partyDetails allOf: - type: object discriminator: propertyName: type mapping: INDIVIDUAL: "#/components/schemas/IndividualPartyResponse" ORGANISATION: "#/components/schemas/OrganisationPartyResponse" properties: partyId: type: string format: uuid description: Unique identifier for the party role: type: string pattern: ^(BORROWER|BUYER|INTRODUCER|OUTGOING_LENDER)$ description: > Allowed Values: [`BORROWER`, `BUYER`, `INTRODUCER`, `OUTGOING_LENDER`] required: - role properties: type: type: string pattern: ^(INDIVIDUAL)$ description: | Allowed Values: [`INDIVIDUAL`] partyDetails: type: object properties: forenames: type: string maxLength: 90 minLength: 1 pattern: ^[A-Za-z][A-Za-z\- ']*$ description: Forename is required for Individual BORROWER and BUYER parties example: James Thomas surname: type: string maxLength: 50 minLength: 1 pattern: ^[A-Za-z][A-Za-z\ - ']*$ description: Surname is required for Individual BORROWER and BUYER parties example: Smith title: type: string description: Title (e.g., "Mr", "Mrs", "Dr") dateOfBirth: type: string format: date description: Date of birth (YYYY-MM-DD) mobile: type: string pattern: ^(\+?\d{1,4}[- ]?)?[\d\s-]{4,20}$ description: Mobile phone number minLength: 4 maxLength: 20 phone: type: string pattern: ^(\+?\d{1,4}[- ]?)?[\d\s-]{4,20}$ description: Home landline phone number minLength: 4 maxLength: 20 email: type: string maxLength: 100 pattern: ^$|(?:[A-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[A-z0-9!#$%&'*+/=?^_`{|}~-]+)*|"(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[A-z0-9](?:[A-z0-9-]*[A-z0-9])?\.)+[A-z0-9](?:[A-z0-9-]*[A-z0-9])?|\[(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?|[A-z0-9-]*[A-z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5A\x53-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\]) example: john.smith@lawfirm.com description: Email address fcaNumber: type: string description: FCA registration number is required only for Individual INTRODUCER party example: "123456" organisationName: type: string maxLength: 160 minLength: 1 pattern: ^[a-zA-ZÀ-ÖØ-öø-ſĀ-ıĴ-ľŁ-ʼnŊ-ŏŐ-őŒ-žǼǺǾẀẂẄỲǽǻǿẁẃẅỳ\d&@£$€¥#'''(){}<>!«»"""\[\]?*=%+\s.,:\/;\\-]+$ description: Organization name example: Mortgage Broker Corp Ltd - type: object required: - type - partyDetails allOf: - type: object discriminator: propertyName: type mapping: INDIVIDUAL: "#/components/schemas/IndividualPartyResponse" ORGANISATION: "#/components/schemas/OrganisationPartyResponse" properties: partyId: type: string format: uuid description: Unique identifier for the party role: type: string pattern: ^(BORROWER|BUYER|INTRODUCER|OUTGOING_LENDER)$ description: > Allowed Values: [`BORROWER`, `BUYER`, `INTRODUCER`, `OUTGOING_LENDER`] required: - role properties: type: type: string pattern: ^(ORGANISATION)$ description: | Allowed Values: [`ORGANISATION`] partyDetails: type: object required: - organisationName properties: organisationName: type: string maxLength: 160 minLength: 1 pattern: ^[a-zA-ZÀ-ÖØ-öø-ſĀ-ıĴ-ľŁ-ʼnŊ-ŏŐ-őŒ-žǼǺǾẀẂẄỲǽǻǿẁẃẅỳ\d&@£$€¥#'''(){}<>!«»"""\[\]?*=%+\s.,:\/;\\-]+$ description: Organization name is required for Organisation BORROWER and BUYER parties example: Smith Ltd registrationNumber: type: string minLength: 6 maxLength: 8 pattern: ^[A-Z0-9]+$ description: Company registration number is required only for Organisation BORROWER, BUYER, OUTGOING_LENDER parties example: "12345678" organisationType: type: string pattern: ^(LIMITED_COMPANY)$ description: > Type of organization is required only only for Organisation BORROWER and BUYER parties Allowed Values: [`LIMITED_COMPANY`] example: LIMITED_COMPANY outgoingLenderAccountNumber: type: string description: Account number with the outgoing lender is required for only Organisation OUTGOING_LENDER party example: "12345678" examples: createInstructionSuccess: summary: Successful instruction creation response value: instructionId: 3fa85f64-5717-4562-b3fc-2c963f66afa6 parties: - partyId: a1b2c3d4-5e6f-7890-abcd-ef1234567890 type: INDIVIDUAL role: BORROWER partyDetails: forenames: John Michael surname: Smith title: Mr dateOfBirth: 1985-06-15 mobile: 7123456789 email: john.smith@email.com "400": description: BAD REQUEST headers: X-API-Version: schema: type: string description: The API version that was used to process the request. X-Request-Correlation-Id: schema: type: string description: The unique identifier for the request content: application/json: schema: type: object properties: errors: type: array items: type: object properties: field: type: string description: Field message: type: string description: Error message example: errors: - field: instructionsDetails.loanAmount message: incorrect data type "401": description: UNAUTHORISED headers: X-API-Version: schema: type: string description: The API version that was used to process the request. X-Request-Correlation-Id: schema: type: string description: The unique identifier for the request content: application/json: schema: type: object properties: errors: type: array items: type: object properties: field: type: string description: Field message: type: string description: Error message example: errors: - message: Unauthorised "403": description: FORBIDDEN headers: X-API-Version: schema: type: string description: The API version that was used to process the request. X-Request-Correlation-Id: schema: type: string description: The unique identifier for the request content: application/json: schema: type: object properties: errors: type: array items: type: object properties: field: type: string description: Field message: type: string description: Error message example: errors: - message: forbidden "409": description: CONFLICT headers: X-API-Version: schema: type: string description: The API version that was used to process the request. X-Request-Correlation-Id: schema: type: string description: The unique identifier for the request content: application/json: schema: type: object properties: errors: type: array items: type: object properties: field: type: string description: Field message: type: string description: Error message example: errors: - message: Instruction already exists "500": description: INTERNAL SERVER ERROR headers: X-API-Version: schema: type: string description: The API version that was used to process the request. X-Request-Correlation-Id: schema: type: string description: The unique identifier for the request content: application/json: schema: type: object properties: errors: type: array items: type: object properties: field: type: string description: Field message: type: string description: Error message example: errors: - message: Internal Server Error "503": description: SERVICE UNAVAILABLE headers: X-API-Version: schema: type: string description: The API version that was used to process the request. X-Request-Correlation-Id: schema: type: string description: The unique identifier for the request content: application/json: schema: type: object properties: errors: type: array items: type: object properties: field: type: string description: Field message: type: string description: Error message example: errors: - message: Service under maintenance security: - oauth2: - x-api:create:instructions components: securitySchemes: oauth2: type: oauth2 flows: clientCredentials: tokenUrl: https://login.pexauk.co.uk/oauth/token scopes: x-api:create:instructions: Create instructions x-api:edit:instructions: Update instructions x-api:cancel:instructions: Cancel instructions ```