> ## Documentation Index > Fetch the complete documentation index at: https://apidoc.mailercloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Create or Update Contact > API to manage your contacts, allowing you to either create new contacts or update existing ones based on your needs. When you send a request, the API first checks if the contact already exists in your database. If the contact is found, the API will automatically update the existing contact with the new information provided. This ensures that your contact list remains up-to-date without creating duplicates. **Custom Property Data:** The API allows you to add custom properties to each contact. You can do this in two ways: - By Property ID: Map the property ID to its corresponding value. - By Personalization Tag: Alternatively, you can use personalization tag for that property to specify values. **Contact Quota Limit:** Please note that you can continue adding or updating contacts until you reach your designated contact quota limit. If you reach your quota limit, further attempts to add new contacts will be rejected until you either remove some existing contacts or increase your quota. ## OpenAPI ````yaml /openapi-v1.json post /contacts/upsert openapi: 3.1.0 info: title: Mailercloud Marketing API version: 1.0.0 description: >- Campaigns, contacts, lists, segments, automations, and webhooks for the Mailercloud Marketing Platform. servers: - url: https://cloudapi.mailercloud.com/v1 security: - apiKey: [] tags: - name: Campaigns - name: Contacts - name: Lists - name: Tags - name: Segments - name: Custom Properties - name: Senders - name: Templates - name: Automations - name: Webhooks - name: Webforms - name: Inbox Tracker - name: Account paths: /contacts/upsert: post: tags: - Contacts summary: Create or Update Contact description: >- API to manage your contacts, allowing you to either create new contacts or update existing ones based on your needs. When you send a request, the API first checks if the contact already exists in your database. If the contact is found, the API will automatically update the existing contact with the new information provided. This ensures that your contact list remains up-to-date without creating duplicates. **Custom Property Data:** The API allows you to add custom properties to each contact. You can do this in two ways: - By Property ID: Map the property ID to its corresponding value. - By Personalization Tag: Alternatively, you can use personalization tag for that property to specify values. **Contact Quota Limit:** Please note that you can continue adding or updating contacts until you reach your designated contact quota limit. If you reach your quota limit, further attempts to add new contacts will be rejected until you either remove some existing contacts or increase your quota. operationId: create-or-update-contact parameters: - name: Content-Type in: header required: true description: Request body type schema: type: string requestBody: required: true content: application/json: schema: type: object properties: city: type: string country: type: string custom_fields: type: object properties: enc_id1: type: string personalisation_tag_4: type: integer department: type: string email: type: string industry: type: string job_title: type: string last_name: type: string lead_source: type: string list_id: type: string middle_name: type: string first_name: type: string company_name: type: string phone: type: string salary: type: integer state: type: string postal_code: type: string contact_type: type: string tags: type: array items: type: string x-examples: Example 1: city: San Francisco country: USA custom_fields: enc_id1: ABC123 personalisation_tag_4: 456 department: Engineering email: john.doe@example.com industry: Software Development job_title: Software Engineer last_name: Doe lead_source: Website list_id: KYHH middle_name: A. first_name: John A. Doe company_name: Tech Innovations Inc. phone: +1-234-567-8901 salary: 95000 state: California postal_code: '94105' contact_type: active tags: - prospect - customer - lead examples: Example-1: value: city: San Francisco country: USA custom_fields: enc_id1: ABC123 personalisation_tag_4: 456 department: Engineering email: john.doe@example.com industry: Software Development job_title: Software Engineer last_name: Doe lead_source: Website list_id: KYHH middle_name: A. first_name: John A. Doe company_name: Tech Innovations Inc. phone: +1-234-567-8901 salary: 95000 state: California postal_code: '94105' contact_type: active tags: - prospect - customer - lead Example-2: value: city: San Francisco country: USA custom_fields: enc_id1: ABC123 personalisation_tag_4: 456 department: Engineering email: john.doe@example.com industry: Software Development job_title: Software Engineer last_name: Doe lead_source: Website list_id: KYHH middle_name: A. first_name: John A. Doe company_name: Tech Innovations Inc. phone: +1-234-567-8901 salary: 95000 state: California postal_code: '94105' contact_type: active tags: - prospect - customer - lead responses: '200': description: OK content: application/json: schema: type: object properties: contact_id: type: string status: type: string x-examples: Example 1: contact_id: fZuKHSuwK status: updated examples: Example-1: value: contact_id: fZuKHSuwK status: updated Example-2: value: contact_id: fZuKHSuwK status: created '400': description: Bad Request content: application/json: schema: type: object properties: error: type: object properties: field: type: string message: type: string x-examples: Example 1: error: field: email message: Invalid email examples: Example-1: value: error: field: email message: Invalid email '401': description: Unauthorized content: application/json: schema: type: object properties: errors: type: array items: type: object properties: field: type: string message: type: string x-examples: Example 1: errors: - field: '' message: Authorization failed examples: Example-1: value: errors: - field: '' message: Authorization failed components: securitySchemes: apiKey: type: apiKey in: header name: Authorization description: >- Your Mailercloud API key (plain text, no Bearer prefix). Create keys in Settings → API. ````