# How do I import data into my account?

Welcome to HelpYouSponsor! This comprehensive guide walks you through the process of importing data into the system. The platform supports importing:

* Recipients (also called Entities)
* Donors (also called Sponsors)
* Sponsorship Relationships
* Payments
* Photos and additional files

This documentation combines both UI instructions and technical details to provide a complete reference for data migration.

> **Note:** *Before importing any data, ensure you've prepared properly*

### Import Strategy

1. **Identify Data Sources**

   Determine where your data currently resides (e.g., spreadsheets, another CRM, etc.)
2. **Define Data Mappings**

   Map fields from your source data to HYS fields
3. **Establish Import Order**

   Always follow this sequence:

   1. First: Recipients (Entities)
   2. Second: Donors (Sponsors)
   3. Third: Relationships (connections between recipients and sponsors)
   4. Fourth: Payments (if applicable)
4. **Set Import Timeline**

   Plan for adequate testing time before final import
5. **Assign Responsibilities**

   Identify who will prepare data, perform imports, and verify results

### Data Preparation Requirements

1. **CSV Format**: Organize your data in CSV format
2. **Required Fields**: Include all required fields for each data type
3. **File Size**: Ensure CSV files are under 10MB
4. **Headers**: Include appropriate headers matching the required field names
5. **Encoding**: Save files as UTF-8 encoded CSVs
6. **Delimiters**: Use comma (,) as the field separator
7. **First Row**: First row must contain column headers

### System Preparation

1. **Form Configuration:** 

   Ensure all necessary forms are configured in HYS:

   1. Recipient profile forms with required fields.
   2. Sponsor profile forms with required fields.
2. **Program Setup:** 

   Verify program settings:

   1. Sponsorship amounts.
   2. Number of sponsors per recipient.
   3. Program type (one-time, recurring, etc)
3. User Access: Confirm admin users have appropriate import permissions

### Import Types and Required Fields

#### Recipient Import

Recipients are individuals who receive sponsorships from donors through your programs. They are referred to as "Entities" in some parts of the system.

#### Required CSV Format for Recipients

<table><thead><tr><th width="126.2578125">Field Name</th><th width="230.73828125">Description</th><th width="81.50390625">Required</th><th width="128.85546875">Format</th><th width="178.6171875">Notes</th></tr></thead><tbody><tr><td>First name</td><td>First name of recipient</td><td>Yes</td><td>Text</td><td></td></tr><tr><td>Last name</td><td>Last name of recipient</td><td>Yes</td><td>Text</td><td></td></tr><tr><td>DOB</td><td>Date of birth</td><td>Yes</td><td>YYYY-MM-DD</td><td></td></tr><tr><td>Gender</td><td>Gender</td><td>Yes</td><td>M/F</td><td></td></tr><tr><td>Program id</td><td>ID of the program</td><td>Yes</td><td>Number</td><td></td></tr><tr><td>Recipient id</td><td>Unique ID (if existing)</td><td>No</td><td>Text/Number</td><td>Used for reference</td></tr><tr><td>Bio</td><td>Biographical information</td><td>No</td><td>Text</td><td></td></tr><tr><td>Location</td><td>Location/address</td><td>No</td><td>Text</td><td></td></tr><tr><td>Status</td><td>Availability status</td><td>No</td><td>Number</td><td>0=Available, 1=Not Available</td></tr><tr><td>SP_NUM</td><td>Number of sponsors needed</td><td>No</td><td>Number</td><td>Defaults to 1 if not specified</td></tr><tr><td>SP_AMOUNT</td><td>Sponsorship amount</td><td>No</td><td>Number (decimal)</td><td>Defaults to program amount if not specified</td></tr></tbody></table>

#### Special Fields for Recipients

* **SP\_NUM**: Indicates how many sponsors are needed for full sponsorship
* **SP\_AMOUNT**: Sets the monthly sponsorship amount (defaults to program setting if not specified)

### Donor Import

Donors are individuals or organizations that sponsor recipients. They are referred to as "Sponsors" in some parts of the system.

#### Required CSV Format for Donors

<table><thead><tr><th width="126.2578125">Field Name</th><th width="230.73828125">Description</th><th width="81.50390625">Required</th><th width="128.85546875">Format</th><th width="178.6171875">Notes</th></tr></thead><tbody><tr><td>First name</td><td>First name of donor</td><td>Yes</td><td>Text</td><td></td></tr><tr><td>Last name</td><td>Last name of donor</td><td>Yes</td><td>Text</td><td></td></tr><tr><td>Email</td><td>Email address</td><td>Yes</td><td>Email format</td><td>Used as username if not specified</td></tr><tr><td>Phone</td><td>Phone number</td><td>No</td><td>Text</td><td></td></tr><tr><td>Address</td><td>Physical address</td><td>No</td><td>Text</td><td></td></tr><tr><td>Donor id</td><td>Unique ID (if existing)</td><td>No</td><td>Text/Number</td><td>Used for reference</td></tr><tr><td>Donor status</td><td>Status</td><td>No</td><td>Text</td><td>Active/Inactive</td></tr><tr><td>Notes</td><td>Additional notes</td><td>No</td><td>Text</td><td></td></tr><tr><td>Username</td><td>Login username</td><td>No</td><td>Text</td><td>Defaults to email if not specified</td></tr><tr><td>Password</td><td>Account password</td><td>No</td><td>Tex</td><td>System generates if not specified</td></tr></tbody></table>

#### Special Fields for Donors

* **username**: If not specified, the system uses the email address as the username.
* **password**: If not specified, the system generates a random password.

### Sponsorship Relationship Import

Sponsorship relationships connect donors to recipients and define sponsorship details.

#### Required CSV Format for Sponsorships

For sponsorships, we require a field in the CSV for the entities that will act as an association between the donor and child. for example, child id in the csv which is related to the child id in the donors record that the donor is sponsoring.
\
Then for the donors we only want the field that carries the donor id from the csv.
\
Next field is the sponsorship amount, so in the CSV you indicate which column contains the sponsorship amounts.
\
Finally, the date when the sponsorship started.

#### Special Considerations for Relationships

* Donors and recipients must already exist in the system.
* The system will update recipient availability based on sponsorship totals.
* If a recipient is fully sponsored, their status will automatically change to "Not Available".

### Payment Import

Payments record financial transactions from donors, optionally linked to specific recipients.

#### Required CSV Format for Payments

For the importation of the payments.
\
We'll require the child id from the csv which will be associated with the child id the donor sponsors.
\
Then we'll require the donor id field in the csv so that we are able to map the payments to the appropriate donor.

For payment details,
\
We'll require amounts column, payment date (the date when payments were made), results or notes written on that payment (can be empty if no notes), Payment method (options are provided like cash, credit card), the payment type (this can be one time payment, recurring payment). default payment method (this will be the payment method that the system will use to track the sponsorship)

### Step-by-Step Import Process

#### Import  Recipients

1. **Navigate to Import Tool**:
   * Log in as administrator
   * Navigate to **Campaigns & Programs > Manage Programs**
   * Find the program you want to import recipients to
   * Click the three dots (⋮) menu on the right side of the program
   * Select **Import** from the dropdown menu
2. **Upload and Configure**:
   * Select your prepared CSV file
   * Choose "Recipients" as the import type
   * Click "Begin Import"
3. **Map Fields**:
   * For each column in your CSV, select the corresponding HYS field
   * If a column should be ignored, select "Do Not Import"
   * Special fields require specific mapping (e.g., SP\_NUM, SP\_AMOUNT, status)
4. **Configure Import Settings**:
   * Select Field for Matching: Typically Internal ID or recipient\_id
   * Specify Default Values: For any required fields not in your CSV
   * Set Custom ID Field: If applicable for your organization
5. **Review and Validate**:
   * Preview how data will be imported
   * Check for any validation warnings
6. **Execute Import**:
   * Click "Import Data" to begin
   * Monitor progress indicator
7. **Receive Confirmation**:
   * System will notify when import completes
   * Summary report shows records imported, skipped, or with errors

### Managing Recipient Availability

The system manages recipient availability based on their sponsorship status:

* **Status 0**: Available/Unsponsored - Recipient is available for sponsorship
* **Status 1**: Not Available/Fully Sponsored - Recipient has all needed sponsors
* **Status 2**: Processing/Checked Out - Recipient is temporarily unavailable (in checkout process)

### Import Donors

1. **Navigate to Import Tool**:
   * Log in as administrator
   * Navigate to **Campaigns & Program > Manage Programs**
   * Find the program you want to import donors to
   * Click the three dots (⋮) menu on the right side of the program
   * Select **Import** from the dropdown menu
2. **Upload and Configure**:
   * Select your prepared CSV file
   * Choose "Donors" as the import type
   * Click "Begin Import"
3. **Map Fields**:
   * For each column in your CSV, select the corresponding HYS field
   * If a column should be ignored, select "Do Not Import"
   * Map username and password fields if you have them, otherwise system defaults apply
4. **Configure Import Settings**:
   * Select Field for Matching: Typically email address or donor\_id
   * Specify Default Values: For any required fields not in your CSV
5. **Review and Validate**:
   * Preview how data will be imported
   * Check for any validation warnings
6. **Execute Import**:
   * Click "Import Data" to begin
   * Monitor progress indicator
7. **Receive Confirmation**:
   * System will notify when import completes
   * Summary report shows records imported, skipped, or with errors

### Import Sponsorship Relationships

1. **Navigate to Import Tool**:
   * Log in as administrator
   * Navigate to **Campaigns & Program > Manage Programs**
   * Find the program you want to import sponsorship relationships to
   * Click the three dots (⋮) menu on the right side of the program
   * Select **Import** from the dropdown menu
2. **Upload and Configure**:
   * Select your prepared CSV file
   * Choose "Sponsorship Relationship" as the import type
   * Click "Begin Import"
3. **Map Fields**:
   * For each column in your CSV, select the corresponding HYS field
   * If a column should be ignored, select "Do Not Import"
   * Ensure donor\_id and recipient\_id are properly mapped
4. **Configure Import Settings**:
   * Verify ID Matching: Confirm how donor and recipient IDs should be matched
   * Specify Default Values: For any required fields not in your CSV
5. **Review and Validate**:
   * Preview how data will be imported
   * Check for any validation warnings
6. **Execute Import**:
   * Click "Import Data" to begin
   * Monitor progress indicator
7. **Receive Confirmation**:
   * System will notify when import completes
   * Summary report shows records imported, skipped, or with errors

### Import Payments

1. **Navigate to Import Tool**:
   * Log in as administrator
   * Navigate to **Campaign & Program  > Manage Programs**
   * Find the program you want to import payments to
   * Click the three dots (⋮) menu on the right side of the program
   * Select **Import** from the dropdown menu
2. **Upload and Configure**:
   * Select your prepared CSV file
   * Choose "Payments" as the import type
   * Click "Begin Import"
3. **Map Fields**:
   * For each column in your CSV, select the corresponding HYS field
   * If a column should be ignored, select "Do Not Import"
   * Ensure donor\_id is properly mapped, and recipient\_id if relevant
4. **Configure Import Settings**:
   * Verify ID Matching: Confirm how donor and recipient IDs should be matched
   * Specify Default Values: For any required fields not in your CSV
5. **Review and Validate**:
   * Preview how data will be imported
   * Check for any validation warnings
6. **Execute Import**:
   * Click "Import Data" to begin
   * Monitor progress indicator
7. **Receive Confirmation**:
   * System will notify when import completes
   * Summary report shows records imported, skipped, or with errors

### Photo Import Methods

HYS offers multiple methods for importing photos for your recipients and donors.

#### Method 1: Individual Upload (Web Interface)

1. **Navigate to Profile**:
   * Find and select the recipient or donor
   * Click "Files" or "Upload Photo" option
2. **Select and Upload Photo**:
   * Choose file from your computer
   * Optionally crop/resize
   * Click "Upload"
3. **Set as Profile Picture**:
   * If uploading multiple photos, select which one to use as the profile picture
   * Save changes

#### Method 2: This can only be donoor by our developers.

1. **Organize children Images:**
   * Have the images to contain the children id for example (1200.png)
   * Place them in a folder to be shared with HYS

2\.  **Uploading done by HYS developers:**

* Once we have received the folder containing images, we'll upload them according to the child id provided in HYS. Please ensure the filenames match with the children ids in the imported data.

### Best Practices

#### Recommended Import Order

1. Recipients first
2. Donors second
3. Sponsorship relationships third
4. Payments fourth

This order ensures that all necessary relationships can be established properly.

#### Data Preparation Tips

* Clean your data before importing
* Validate required fields are present
* Check for formatting issues
* Remove duplicates
* Use consistent date formats (YYYY-MM-DD)
* Save as UTF-8 encoded CSV files

#### Testing Your Import

1. Create a test sample with 5-10 records
2. Import the sample
3. Verify the data appears correctly
4. Proceed with the full import once verified

#### Data Backup

* Keep backups of original data
* Save copies of all CSV files
* Take screenshots of import confirmations

#### Data Validation Tips

* Ensure recipient IDs are unique
* Verify donor emails are valid format
* Confirm relationships reference valid IDs
* Check that dates follow YYYY-MM-DD format
* Verify numeric fields contain only number

### Troubleshooting Common Issues

<table><thead><tr><th width="267.7265625">Issue</th><th>Solution</th></tr></thead><tbody><tr><td>CSV format errors</td><td>Verify the file is properly formatted with headers in the first row</td></tr><tr><td>Missing required fields</td><td>Check the error report to identify and add missing data</td></tr><tr><td>Duplicate records</td><td>Remove duplicates from your import file</td></tr><tr><td>Date format issues</td><td>Ensure all dates follow YYYY-MM-DD format</td></tr><tr><td>Relationship failures</td><td>Verify that referenced IDs exist in the system before importing relationships</td></tr><tr><td>UTF-8 encoding issues</td><td>Resave your file with UTF-8 encoding</td></tr><tr><td>File size too large</td><td>Split large files into multiple smaller files under 10MB</td></tr><tr><td>Sponsorship status not updating</td><td>Verify that relationship data is correctly formatted with valid amounts</td></tr><tr><td>Photo linking failures</td><td>Ensure filenames exactly match recipient IDs</td></tr><tr><td>Import timeout</td><td>Break large imports into smaller batches</td></tr></tbody></table>

### Sample CSV Templates

#### Recipients Sample

```csv
first_name,last_name,dob,gender,program_id,recipient_id,bio,location,status,SP_NUM,SP_AMOUNT
John,Doe,2010-05-15,M,1,R1001,"John is a bright student who enjoys math.",Nairobi,0,1,35.00
Jane,Smith,2012-03-20,F,1,R1002,"Jane loves reading and wants to become a doctor.",Lagos,0,2,35.00
```

#### Donors Sample

```csv
first_name,last_name,email,phone,address,donor_id,donation_status,notes,username,password
Robert,Johnson,robert@example.com,555-123-4567,"123 Main St, Anytown",D2001,Active,"Monthly donor since 2022",,
Sarah,Williams,sarah@example.com,555-987-6543,"456 Oak Ave, Somewhere",D2002,Active,"Prefers email communication",,
```

#### Sponsorships Sample

```csv
donor_id,recipient_id,start_date,sponsorship_amount,frequency,program_id,end_date,status
D2001,R1001,2023-01-15,35.00,Monthly,1,,Active
D2002,R1002,2023-02-20,35.00,Monthly,1,,Active
```

#### Payments Sample

```csv
donor_id,recipient_id,amount,payment_date,payment_method,transaction_id,notes
D2001,R1001,35.00,2023-01-15,Credit Card,TX100123,"Initial payment"
D2002,R1002,105.00,2023-02-20,Bank Transfer,TX100124,"Quarterly payment"
```

### Support

If you encounter issues during the import process, please contact our support team:

* Email: <support@helpyousponsor.com>