Guides
API Reference
Start typing to search…

Lien Filing

Introduction

This guide explains how to use the API endpoints for filing liens. A lien is a legal claim or right against a property, typically used as security for a debt or obligation. Filing a lien allows a creditor to secure their interest in a debtor's property.

The lien filing process in this API is designed to be flexible and user-friendly, mimicking the experience of working on a draft document. Users can gradually fill out the lien filing form over time, saving their progress as they go, without the need to submit it immediately. This approach allows for careful review and collaboration before final submission.

Endpoints Overview

  1. Create a Lien Filing Submission
  2. Get Lien Filing Submissions
  3. Get a Specific Lien Filing Submission
  4. Update a Lien Filing Submission
  5. Submit a Lien Filing
  6. Cancel a Lien Filing Submission
  7. Delete a Lien Filing Submission
  8. Manage Attachments

The Draft-Like Nature of Lien Filings

One of the key features of this API is its support for a draft-like workflow:

  1. Minimal Initial Creation: A lien filing can be created with virtually no payload, requiring only the business_id in the URL parameters. This allows users to initiate a filing and fill in details later.

  2. Gradual Population: Users can add or update information in multiple steps, similar to how one might work on a draft document. This is particularly useful for complex filings that may require input from multiple parties or departments.

  3. Save and Resume: The API allows users to save their progress at any point and resume work on the filing later. This is ideal for situations where all information may not be immediately available.

  4. Review and Revision: Before submission, users can review the entire filing, make revisions as needed, and ensure all details are correct.

  5. Final Submission: Only when the user is satisfied with all the details do they submit the filing for processing.

Step-by-Step Guide

1. Create a Lien Filing Submission

Example: Creating a Minimal Lien Filing

To start a lien filing with minimal information:

POST /businesses/{business_id}/lien_submissions

You can send an empty JSON object as the payload:

{}

This will create a draft lien filing associated with the specified business. The response will include a filing_id that you can use for subsequent updates.

1a. Create a Lien Filing Submission for an Individual

To start a lien filing for an individual, you must first create a person to associate the lien filing with

Example: Creating a Minimal Lien Filing for an Individual

POST /people

Example payload (see full documentation of this route here ):

{
  "first_name": "John",
  "last_name": "Doe",
  "ssn": "123456789",
}

The response from this route contains an id for the created person. Use this on the create individual lien filing endpoint

POST /people/{person_id}/lien_submissions

Payloads are identical between lien filings for individuals and businesses. To create a minimal lien filing use an empty JSON object

{}

Example: Creating a Fully Filled out Lien Filing

Same as filing with minimal payload, use the create lien filing endpoint:

POST /businesses/{business_id}/lien_submissions

Example payload:

{
  "filing_type": "UCC1",
  "state": "AL",
  "debtors": [
    {
      "mailing_address": "7812 2nd NW Ave",
      "city": "Bradenton",
      "state": "FL",
      "postal_code": "34210",
      "capacity": "NONE_OF_THE_ABOVE",
      "organization_type": "C_CORPORATION",
      "organization_name": "J.B, INC.",
      "type": "ORGANIZATION",
    }
  ],
  "secured_parties": [
    {      
      "mailing_address": "205 Franklin Street",
      "city": "Brooklyn",
      "state": "NY",
      "postal_code": "11222",
      "capacity": "NONE_OF_THE_ABOVE",
      "organization_type": "SOLE_PROPRIETORSHIP",
      "organization_name": "At at Joe's",
      "type": "ORGANIZATION"
    }
  ],
  "reference_data": "123456",
  "submission_filing_name": "My new lien filing",
  "collateral_statements": {
    "collateral_statement_designation": "NONE",
    "text": "All inventory, equipment, accounts, and proceeds now owned or hereafter acquired by the debtor, including but not limited to the property located at 123 Main Street, Anytown, CA 90210.",
    "type": "TEXT"
  },
  "search_to_reflect": true
}

This will create a draft lien filing submission.

2. Get Lien Filing Submissions

To retrieve a list of lien filing submissions:

GET /lien_submissions

You can use query parameters to filter and paginate the results:

  • limit: Maximum number of submissions to return (default: 10)
  • offset: Number of submissions to skip (default: 0)
  • q: Search by filename
  • status: Filter by submission status

3. Get a Specific Lien Filing Submission

To retrieve details of a specific lien filing submission:

GET /lien_submissions/{filing_id}

4. Update a Lien Filing Submission

The update endpoint allows for flexible and gradual updates to your lien filing submission. It's important to understand how the update process works to effectively manage your lien filing information.

Endpoint

PUT /lien_submissions/{filing_id}

Update Behavior

When updating a lien filing submission, keep the following behaviors in mind:

  1. Partial Updates: You can send a partial payload containing only the fields you want to update. Fields not included in the payload will retain their current values.

  2. Overwriting Values: When you include a field in your update payload, it will overwrite the current value for that field entirely.

  3. Array Fields: For array fields (like debtors or secured_parties), sending an array will replace the entire existing array. To add or remove individual items, you need to send the complete updated array.

  4. Nested Objects: For nested objects (like collateral_statements), sending the object will replace the entire existing object.

  5. Null Values: If you explicitly set a field to null, it will clear the value of that field.

Examples of Update Behavior

Let's walk through some examples to illustrate these behaviors:

Initial Lien Filing State:
{
  "submission_filing_name": "2023 Equipment Lien",
  "reference_data": "New manufacturing equipment",
  "debtors": [
    {
      "mailing_address": "7812 2nd NW Ave",
      "city": "Bradenton",
      "state": "FL",
      "postal_code": "34210",
      "capacity": "NONE_OF_THE_ABOVE",
      "organization_type": "C_CORPORATION",
      "organization_name": "J.B, INC.",
      "type": "ORGANIZATION",
    }
  ],
  "secured_parties": [],
  "collateral_statements": {
    "type": "TEXT",
    "text": "All manufacturing equipment purchased from Acme Manufacturing on 1/1/2023",
    "collateral_statement_designation": "NO_DESIGNATION"
  }
}
Example 1: Updating a Single Field

To update just the submission_filing_name:

{
  "submission_filing_name": "2023 Updated Equipment Lien"
}

This will change only the submission_filing_name while leaving all other fields unchanged.

Example 2: Updating an Array Field

To add a secured party:

{
  "secured_parties": [
    {
      "type": "ORGANIZATION",
      "organization_name": "Acme Finance Inc",
      "organization_type": "CORPORATION",
      "mailing_address": "456 Business Ave",
      "city": "Metropolis",
      "state": "NY",
      "postal_code": "10001"
    }
  ]
}

This will replace the empty secured_parties array with the new array containing one secured party.

Example 3: Updating a Nested Object

To update the collateral statement:

{
  "collateral_statements": {
    "type": "TEXT",
    "text": "All manufacturing equipment purchased from Acme Manufacturing on 1/1/2023, including CNC Machine (Serial: CN12345)",
    "collateral_statement_designation": "NO_DESIGNATION"
  }
}

This will replace the entire collateral_statements object with the new one.

Example 4: Clearing a Field

To clear the reference_data:

{
  "reference_data": null
}

This will set the reference_data field to null, effectively clearing its value.

Best Practices for Updating

  1. Fetch Before Update: If you're unsure about the current state of the lien filing, fetch it first using the GET endpoint before making updates.

  2. Incremental Updates: Make small, focused updates rather than trying to update everything at once. This reduces the risk of unintended changes.

  3. Review Changes: After each update, fetch the lien filing again to confirm that the changes were applied as expected.

  4. Be Cautious with Arrays: When updating array fields, be sure to include all existing items you want to keep, not just the new ones you're adding.

  5. Use Null Carefully: Only set fields to null when you explicitly want to clear their values.

By understanding these update behaviors, you can effectively manage your lien filing submissions, gradually building and refining them until they're ready for final submission.

5. Submit a Lien Filing

When you're ready to submit your lien filing, you'll use the submit endpoint. This process involves a series of validations to ensure that all required information is present and correctly formatted.

Endpoint

POST /lien_submissions/{filing_id}/submit

This will change the status of the submission to Requested and initiate the filing process.

Validation Process

When you call the submit endpoint, the system performs a series of checks on your lien filing submission. Here's an overview of the validation process:

  1. Submission Status Check:

    • The system first checks if the submission is in a valid status for submission (Draft or NeedsAttention).
    • If the submission is already in a submitted or processed state, the submission will be rejected.

  2. Jurisdiction Validation:

    • The system verifies that the filing jurisdiction (state) is supported.
    • If the jurisdiction is not supported, the submission will be rejected.

  3. Required Fields Check:

    • The system ensures all required fields are present. These include:
      • Email contact
      • Filing name
    • If any required field is missing, the submission will be rejected.

  4. Party Information Validation:

    • The system checks that there is at least one secured party.
    • For each party (debtor and secured), it validates:
      • For individuals: first name and last name are present
      • For organizations: organization name is present
      • Address information is complete (street, city, state, postal code)
    • If any party information is incomplete, the submission will be rejected.

  5. Collateral Statement Check:

    • If the collateral statement type is set to "Attachments", the system verifies that at least one attachment is present.
    • If the type is "Text", it checks that the text field is not empty.
    • If the collateral statement is missing or incomplete, the submission will be rejected.

Example Validation Errors

Here are some example error responses you might receive if validation fails:

  1. Missing party information:
{
  "code": 432,
  "message": "Cannot submit a lien filing due to validation errors.",
  "uri": null,
  "metadata": {
    "reason": "Missing lien party street address."
  }
}
  1. Unsupported jurisdiction:
{
  "code": 432,
  "message": "Cannot submit a lien filing due to validation errors.",
  "uri": null,
  "metadata": {
    "reason": "Lien filing is currently not supported in AK.",
    "unsupported_jurisdiction_states": ["AK", "HI"]
  }
}
  1. Missing required field:
{
  "code": 432,
  "message": "Cannot submit a lien filing due to validation errors.",
  "uri": null,
  "metadata": {
    "reason": "Missing email contact."
  }
}
  1. Missing collateral statement:
{
  "code": 432,
  "message": "Cannot submit a lien filing due to validation errors.",
  "uri": null,
  "metadata": {
    "reason": "Missing collateral statement attachments."
  }
}

Understanding Validation Error Responses

When a validation error occurs, the API will return a JSON response with the following structure:

  • code: An integer representing the specific error code. For validation errors, this is typically 432.
  • message: A general message indicating that the lien filing couldn't be submitted due to validation errors.
  • uri: This field is typically null for validation errors.
  • metadata: An object containing additional details about the error:
    • reason: A specific description of what caused the validation to fail.
    • Additional fields may be present depending on the nature of the error (e.g., unsupported_jurisdiction_states).

Best Practices for Handling Validation Errors

  1. Check thereason : Always look at the reason field in the metadata object for specific information about what needs to be corrected.

  2. Systematic Error Handling: Develop your client application to handle these structured error responses systematically. This can help automate the process of identifying and correcting errors.

  3. Logging: Consider logging these error responses for debugging and audit purposes.

  4. User Feedback: If you're developing a user interface, translate these error messages into user-friendly notifications to guide users in correcting their submissions.

  5. Incremental Corrections: Address one error at a time. After correcting an error, attempt to submit again, as there may be multiple validation issues that need to be resolved sequentially.

Best Practices for Submission

  1. Pre-submission Review: Before submitting, use the GET endpoint to review all details of your lien filing submission.

  2. Incremental Updates: If you find any missing or incorrect information, use the UPDATE endpoint to correct it before attempting to submit again.

  3. Handle Validation Errors: If you receive a validation error, carefully read the error message, make the necessary corrections, and then try to submit again.

  4. Attachment Management: If using attachments for collateral statements, ensure all necessary documents are uploaded before submission.

  5. Status Tracking: After a successful submission, continue to monitor the status of your lien filing using the GET endpoint, as further processing may be required.

By understanding this validation process, you can ensure that your lien filing submissions are complete and accurate, reducing the likelihood of delays or rejections in the filing process.

6. Cancel a Lien Filing Submission

To cancel a lien filing submission that is in "Needs Attention" status:

POST /lien_submissions/{filing_id}/cancel

7. Delete a Lien Filing Submission

To delete a draft lien filing submission:

DELETE /lien_submissions/{filing_id}

8. Manage Attachments

Upload Attachments

To upload attachments for a lien filing submission:

POST /lien_submissions/{filing_id}/attachments

Use multipart/form-data to upload PDF files.

Get Attachments

To retrieve a list of attachments for a lien filing submission:

GET /lien_submissions/{filing_id}/attachments

Delete an Attachment

To delete a specific attachment:

DELETE /lien_submissions/{filing_id}/attachments/{attachment_id}

Download an Attachment

To download a specific attachment:

GET /lien_submissions/{filing_id}/attachments/{attachment_id}

Secured Party Masking

Secured party masking is a feature that allows you to protect the identity of a secured party in a lien filing. This can be useful in situations where privacy is a concern or when the secured party's identity should not be publicly disclosed.

How Secured Party Masking Works

When you create or update a secured party in a lien filing, you can set the masked field to true. This instructs the system to hide the secured party's information in public records and certain API responses.

Using Secured Party Masking

To use secured party masking, include the masked field when adding or updating a secured party:

{
  "secured_parties": [
    {
      "type": "ORGANIZATION",
      "organization_name": "Confidential Lender LLC",
      "organization_type": "LLC",
      "mailing_address": "789 Private Lane",
      "city": "Secretville",
      "state": "CA",
      "postal_code": "90210",
      "masked": true
    }
  ]
}

Effects of Masking

When a secured party is masked:

  1. The secured party's information will not be visible in public records or searches.
  2. The API will return limited information about the masked secured party in most responses.
  3. The full information of the masked secured party will only be available to authorized users through specific API endpoints.

Unmasking a Secured Party

If you need to unmask a previously masked secured party, you can update the lien filing and set masked to false:

{
  "secured_parties": [
    {
      "type": "ORGANIZATION",
      "organization_name": "Confidential Lender LLC",
      "organization_type": "LLC",
      "mailing_address": "789 Private Lane",
      "city": "Secretville",
      "state": "CA",
      "postal_code": "90210",
      "masked": false
    }
  ]
}

Best Practices for Secured Party Masking

  1. Use Judiciously: Only mask secured parties when there's a legitimate need for privacy.

  2. Consistent Application: If you're masking one secured party in a filing, consider whether other parties should also be masked for consistency.

  3. Record Keeping: Maintain internal records of masked secured parties, as their information may not be readily available in public searches.

  4. Legal Compliance: Ensure that masking complies with all applicable laws and regulations in your jurisdiction.

  5. Authorized Access: Implement proper authorization checks in your application to ensure that only authorized users can view unmasked information.

  6. Updates and Amendments: Remember that changing the masked status (either masking or unmasking) may require filing an amendment to the lien in some jurisdictions.

By using secured party masking effectively, you can balance the need for public record-keeping with the privacy concerns of certain secured parties involved in lien filings.

Filing a UCC-3 (Amendment)

A UCC-3 form is used to amend, continue, assign, terminate, or make other changes to an existing UCC-1 filing. It's an essential tool for maintaining accurate and up-to-date lien records. Here are the main types of UCC-3 filings:

  1. Termination: Indicates that the secured party no longer claims a security interest in the collateral.
  2. Continuation: Extends the effectiveness of the original filing for an additional period.
  3. Assignment: Transfers all or part of the secured party's rights to a new secured party. There are two types of assignments:
    • Full Assignment: The entire interest in the collateral is transferred to a new secured party. The original secured party relinquishes all rights to the collateral, and all future actions related to the financing statement will be handled by the new secured party.
    • Partial Assignment: Only a portion of the interest in the collateral is transferred to a new secured party. The original secured party retains some rights to the collateral. Both the original and new secured parties may have rights to take actions related to the financing statement, but only for their respective portions of the collateral.
  4. Debtor Amendment: Used to add, delete, or modify information about one or more debtors associated with the financing statement. This could include updating a debtor's name, address, or other identifying information.
  5. Secured Party Amendment: Allows for the addition, deletion, or modification of information about one or more secured parties. This might involve updating a secured party's contact details or adding a new secured party to the filing.
  6. Collateral Amendment: Enables changes to the description of the collateral covered by the financing statement. This could involve adding new items to the collateral list, removing items, or clarifying the existing collateral description.

Using the API to File a UCC-3

To file a UCC-3 using our API, follow these steps:

  1. Route:

    • URL: /lien_submissions/{filing_id}/amend
    • Method: POST

  2. Path Parameters:

    • filing_id (UUID): The unique identifier of the original lien filing you want to amend.

  3. Request Body:

    To start a UCC-3 lien filing document, the request should at minimum include a JSON object with the following properties:

    • filing_type (string): Should be set to "UCC3" for amendments.
    • amendment_action (object): Specifies the type and details of the amendment action.

    The amendment_action field is polymorphic and can accept different structures based on the type of amendment (see the API reference for possible structures).

  4. Response:

    • On success (HTTP 201), you'll receive a JSON object containing details of the created UCC-3 filing submission.
    • If the original filing is not found, you'll get a 404 error.

  5. Important Notes:

    • Ensure you have the correct filing_id for the original lien you want to amend.
    • The amendment_action field is crucial for specifying the type and details of your amendment. Make sure to provide the correct structure based on your amendment type.
    • If you set amendment_action to null, it will preserve the existing server value for this field, causing no changes.
    • Always verify the information before submitting, as amendments can have significant legal implications.

Example of UCC-3 request payloads (for both creation POST and update PATCH route methods)

The examples below only focus on all the different possible amendment_action payloads, remaining required fields still have to be provided in order to have a complete filings that successfully passes the validation on POST /lien_submissions/{filing_id}/submit. See the Create New UCC3 Lien Filing Submission for the full model definition.

Continuation

The continuation structure is used when you want to extend the effectiveness of the original filing for an additional period.

{
    "filing_type": "UCC3",
    "amendment_action": {
        "type": "CONTINUATION"
    }
}

Termination

The termination structure is used when you want to indicate that the financing statement is no longer effective with respect to the interest of the secured party authorizing the termination. This effectively ends the security interest in the collateral.

{
    "filing_type": "UCC3",
    "amendment_action": {
        "type": "TERMINATION"
    }
}

Partial Assignment

The partial assignment structure is used when you want to transfer only a portion of the rights to the collateral to a new secured party. Here's an explanation of the key components:

  • type: Set to "PARTIAL" to indicate a partial transfer of rights.
  • secured_parties: An array of new secured parties receiving the assigned rights.
  • collateral_statements: Specifies the collateral being assigned.

This structure allows you to specify which portion of the collateral is being assigned and to whom, providing flexibility in transferring secured interests.

{
    "filing_type": "UCC3",
    "amendment_action": {
        "type": "ASSIGNMENT",
        "assignment": {
            "type": "PARTIAL",
            "secured_parties": [
                {
                    "type": "ORGANIZATION",
                    "organization_name": "Quantum Dynamics Solutions, LLC",
                    "mailing_address": "789 Innovation Boulevard",
                    "city": "Tech Harbor",
                    "state": "CA",
                    "postal_code": "94105"
                }
            ],
            "collateral_statements": {
                "collateral_statement_designation": "NONE",
                "text": "The new collateral statement.",
                "type": "TEXT"
            }
        }
    }
}

Full Assignment

The full assignment structure is used when you want to transfer all rights to the collateral to a new secured party. Here's an explanation of the key components:

  • type: Set to "FULL" to indicate a complete transfer of rights.
  • secured_parties: An array of new secured parties receiving the assigned rights.

This structure allows you to specify the new secured party or parties who will be taking over the entire security interest. Unlike partial assignment, there's no need to specify collateral statements as the entire security interest is being transferred.

{
    "filing_type": "UCC3",
    "amendment_action": {
        "type": "ASSIGNMENT",
        "assignment": {
            "type": "FULL",
            "secured_parties": [
                {
                    "type": "ORGANIZATION",
                    "organization_name": "Quantum Dynamics Solutions, LLC",
                    "mailing_address": "789 Innovation Boulevard",
                    "city": "Tech Harbor",
                    "state": "CA",
                    "postal_code": "94105"
                }
            ]
        }
    }
}

Debtor amendment — adding debtors

This structure is used for adding new debtors to an existing UCC filing through a UCC-3 amendment. It allows you to specify one or more debtors to be added to the filing.

Each debtor object in the array includes essential information such as the organization name, type, and address details. This structure ensures that all necessary information for adding new debtors is provided in a clear and organized manner.

{
    "filing_type": "UCC3",
    "amendment_action": {
        "type": "DEBTOR_AMENDMENT",
        "amendment": {
            "type": "ADD",
            "debtors": [
                {
                    "type": "ORGANIZATION",
                    "organization_name": "Acme, Inc",
                    "organization_type": "LLC",
                    "mailing_address": "123 St",
                    "city": "City",
                    "state": "AL",
                    "postal_code": "1345"
                }
            ]
        }
    }
}

Debtor edit amendment

This structure is used for modifying existing debtor information in a UCC filing through a UCC-3 amendment. It allows you to update the details of one or more debtors already present in the filing.

The amendment object includes:

  • type: Set to "EDIT" to indicate that this is an edit operation.
  • amending_debtors: An array of objects, each representing a debtor to be modified.

Each object in the amending_debtors array contains:

  • amending_debtor_id: The unique identifier of the existing debtor to be modified.
  • new_debtor: An object containing the updated information for the debtor.

The new_debtor object includes all the fields that can be updated for a debtor, such as organization name, type, and address details. This structure ensures that you can precisely specify which debtors to modify and what information to update.

{
    "filing_type": "UCC3",
    "amendment_action": {
        "type": "DEBTOR_AMENDMENT",
        "amendment": {
            "type": "EDIT",
            "amending_debtors": [
                {
                    "amending_debtor_id": "9919e101-a60f-40ac-8e5a-ee642ecb3819",
                    "new_debtor": {
                        "type": "ORGANIZATION",
                        "organization_name": "GREENTECH SOLUTIONS, INC.",
                        "organization_type": "CORPORATION",
                        "mailing_address": "789 Innovation Drive",
                        "city": "Austin",
                        "state": "TX",
                        "postal_code": "78701",
                    }
                }
            ]
        }
    }
}

Debtor removal amendment

This structure is used for removing existing debtors from a UCC filing through a UCC-3 amendment. It allows you to delete one or more debtors that are currently associated with the filing.

The amendment object includes:

  • type: Set to "DELETE" to indicate that this is a removal operation.
  • deleted_debtor_ids: An array of strings, each representing the unique identifier of a debtor to be removed from the filing.

This structure provides a straightforward way to specify which debtors should be deleted from the UCC filing. By using the unique identifiers, you can ensure that the correct debtors are removed without ambiguity.

{
    "filing_type": "UCC3",
    "amendment_action": {
        "type": "DEBTOR_AMENDMENT",
        "amendment": {
            "type": "DELETE",
            "deleted_debtor_ids": [
                "9919e101-a60f-40ac-8e5a-ee642ecb3819"
            ]
        }
    }
}

Add, Restate and Delete Collateral Statement Amendment

This structure is used for adding, editing, or removing collateral statements in a UCC filing through a UCC-3 amendment. The structure remains consistent across these operations, but the meaning changes based on the collateral_amendment_type.

  • For ADD, the provided collateral statement is added to the existing collateral.
  • For RESTATE, the provided collateral statement replaces all existing collateral statements.
  • For DELETE, the provided collateral statement is removed from the existing collateral.

The amendment_action object includes:

  • type: Set to "COLLATERAL_AMENDMENT" to indicate that this is a collateral-related amendment.
  • collateral_amendment_type: Specifies the type of amendment (ADD, RESTATE, or DELETE).
  • collateral_statements: Contains the collateral information, which can be of type TEXT or ATTACHMENTS (not shown in this example).

This structure allows for flexible modification of collateral information in the UCC filing, enabling you to add new collateral, update existing information, or remove specific collateral statements as needed.

{
    "filing_type": "UCC3",
    "amendment_action": {
        "type": "COLLATERAL_AMENDMENT",
        "collateral_amendment_type": "ADD",
        "collateral_statements": {
            "type": "TEXT",
            "text": "All equipment, inventory, and accounts receivable now owned or hereafter acquired by the debtor."
        }
    }
}

Best Practices for Using the Lien Filing API

To make the most effective use of the lien filing API and ensure smooth processing of your lien filings, consider the following best practices:

  1. Flexible Population Approach:

    • You have the flexibility to populate a lien filing in two main ways:
      a) Full Payload: You can create or update a lien filing with a complete payload containing all necessary information at once.
      b) Gradual Population: You can start with minimal information and gradually add or update details over time.
    • Choose the approach that best fits your workflow or application design:
      • For integrations with user interfaces where users might save drafts and return later, the gradual population approach works well.
      • For automated systems with all information available upfront, using a full payload might be more efficient.

  2. Start with Minimal Information (if using gradual population):

    • Begin by creating a lien filing with just the required business_id in the URL.
    • This allows you to get a filing_id early in the process, which you can use for subsequent updates.

  3. Incremental Updates (for gradual population):

    • Build your lien filing gradually by making small, focused updates rather than trying to populate all information at once.
    • This approach reduces the risk of errors and allows for easier tracking of changes.

  4. Regular Saving:

    • Whether using full payload or gradual population, save your progress frequently by making API calls to update the lien filing.
    • This prevents loss of work and allows collaboration if multiple people are working on the filing.

  5. Fetch Before Update:

    • Before making updates, especially to complex fields like arrays, fetch the current state of the lien filing.
    • This ensures you have the most up-to-date information and helps prevent unintended overwrites.

  6. Careful Array Handling:

    • When updating array fields (like debtors or secured_parties), always include all existing items you want to keep, not just the new ones.
    • Remember that sending an array will replace the entire existing array.

  7. Validate As You Go:

    • Regularly check the lien filing for completeness and accuracy, especially before submission.
    • Use the GET endpoint to review all details of your lien filing submission.

  8. Handle Validation Errors Systematically:

    • Develop a systematic approach to handling validation errors returned by the API.
    • Address one error at a time, making corrections and resubmitting until all issues are resolved.

  9. Use Secured Party Masking Judiciously:

    • Only use the masking feature when there's a legitimate need for privacy.
    • Ensure consistency in masking across related parties in a filing.

  10. Manage Attachments Carefully:

    • If using attachments for collateral statements, ensure all necessary documents are uploaded before submission.
    • Remember that changing from text to attachments (or vice versa) for collateral statements will replace the existing content.

  11. Monitor Submission Status:

    • After submission, continue to monitor the status of your lien filing using the GET endpoint.
    • Be prepared to respond promptly if the status changes to Needs Attention.

  12. Implement Proper Error Handling:

    • Develop robust error handling in your application to deal with various API responses.
    • Log error responses for debugging and audit purposes.

  13. Consider User Experience:

    • If developing a user interface, translate API responses and error messages into user-friendly notifications.
    • Design your interface to support both full payload and gradual population approaches, allowing users to save drafts and return to them later.

  14. Stay Informed About Jurisdictional Requirements:

    • Be aware that lien filing requirements can vary by jurisdiction.
    • Regularly check for updates to the API or changes in lien filing regulations that may affect your process.

  15. Secure Access to Sensitive Information:

    • Implement proper authorization checks in your application to ensure that only authorized users can view sensitive information, especially for masked secured parties.

By following these best practices, you can create a more efficient and error-resistant process for managing lien filings through the API, whether you're using a full payload approach or gradually populating the filing. Remember that lien filing is often a complex legal process, and while this API aims to streamline it, it's always advisable to consult with legal professionals when dealing with complex filings or unique situations.

Jurisdiction County

In the states of Louisiana, Georgia, and Oklahoma, providing county information is essential for lien filings because these states have specific local requirements that mandate the identification of the county where the property is located. This is necessary to ensure that the lien is properly recorded and recognized within the correct jurisdiction.

Updated about 2 months ago